swagger简介
Swagger 是一个简单、强大的 RestfulAPI 文档生成管理工具,通过 swagger-spring 项目实现了与 Sping MVC 框架的无缝集成功能,方便生成 spring restful 风格的接口文档,在项目中集成这个工具,根据我们自己的配置信息能够自动为我们生成一个 API 文档展示页,可以在浏览器中直接访问查看项目的接口信息(如下图 1 所示),同时 swagger-ui 还可以测试 spring restful 风格的接口功能,可以对项目提供的每一个 API 接口进行相应的测试。Swagger生成的API文档是实时更新的, API接口有任何改动都会在文档中及时的表现出来。其官方网站为:http://swagger.io/。
- 前后端分离
前端-------->前端控制层,视图层
↑
|
| Restful API
|
↓
后端-------->后端控制层,服务层,数据访问层
- 前后分离好处:相对独立且松耦合
- 导致问题
- 前后端集成--->CI/CD
- 前端或者后端无法做到"及时商量,尽早解决",最终导致集中爆发
- CI:持续集成(Continuous integration)是一种软件开发实践,每次集成都通过自动化的构建(包括编译,发布,自动化测试)来验证,从而尽早地发现集成错误。
- CD:持续部署(continuous deployment)是通过自动化的构建、测试和部署循环来快速交付高质量的产品。
- 前后端集成--->CI/CD
- 解决方案
- 首先定义schema,并实时跟踪最新的API,降低集成风险
- swagger
- Restful API文档在线自动生成器--->API文档与API定义自动更新
- 直接运行,在线测试API
- 支持多种语言(比如:java,php等)
- 官网https://swagger.io
- spring集成swagger--->springfox
- springfox-swagger2
- swagger-springmvc
- swagger在linux中使用会被配置的nginx拦截
- 需要将前端工程及缓存配置注释掉
- 项目环境
- jdk1.8--->swagger2必须使用1.8以上版本jdk
- spring-4.1.7
- mybatis-3.3.2
- springmvc集成springfox-swagger2构建Restful API
- maven依赖
- springfox-swagger2
- springfox-swagger-ui
- guawa:google相关
- mapstruct-jdk8:对象结构相关
- jackson
- jackson-core
- jackson-databind
- jackson-annotations
- maven依赖
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-aop</artifactId>
</exclusion>
<exclusion>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-aop</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>19.0</version>
</dependency>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-jdk8</artifactId>
<version>1.1.0.Final</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${jackson.verson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.verson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${jackson.verson}</version>
</dependency>
- 集成配置步骤
- 在pom.xml文件中添加swagger2相关依赖
- swagger2配置类:SwaggerConfig.java(官网下载)
- @ComponentScan:设置swagger扫描包
- @EnableSwagger2:使swagger2生效
- @Configuration:自动在本类上下文加载一些环境变量信息
- springmvc配置文件
-
- 使用的页面是静态资源,配置此注解,不让springmvc进行拦截-->
<mvc:default-servlet-handler/>
<!--添加指定扫描,让swagger的注解生效-->
<context:component-scan/>
- 使用的页面是静态资源,配置此注解,不让springmvc进行拦截-->
- 具体应用
- api加入swagger
- 通过在api上添加注解实现,api文件的同步效果
- @Api
- 表明可供swagger展示的接口类(用在类上面)
- @ApiOperation
- 描述api方法(用在方法上面)
- @ApiParam
- 单个参数描述
- @ApiModel
- 用对象接收参数(用在类上面)
- @ApiModelProperty
- 用对象接收参数时,描述对象的一个字段(用在属性上面)
- SystemCommentController介绍
- api加入swagger
nginx配置访问swagger
- 访问swagger页面
- http://ip:port/{context-path}/swagger-ui.html
- 问题
- 生产环境下,只开放80端口,通过tomcat无法访问swagger
- 解决方案
- 通过nginx配置swagger的访问
- 修改nginx.conf文件
- 通过nginx配置swagger的访问
- swagger在线帮助文档
- http://docs.swagger.io/swagger-core/apidocs