swagger Spring Boot集成Swagger2

目前互联网开发市场流行真正的前后分离。后面提供数据API接口，前台负责请求和渲染数据。那么，当我们在程写接口的时候，最不方便的就是我们需要写文档，写完之后还要测试接口。今天我们介绍一下界面文档编写和测试大师swag，它也是一个被很多企业重用的API管理工具。这个DEMO的开发环境是Maven+Spring Boot 2 . 1 . 0+JDK 8+swag 2 . 9 . 2

1.快速构建Spring Boot项目

选择Maven在https://start.spring.io/,搭建Java项目，然后选择Spring Boot 2 . 1 . 0版，Group是com.mage，Artifact是swagger _ restful，Dependencies选择web，从而快速搭建基于Spring Boot的web项目。如下图:

2.用IDEA打开项目

解压swagger _ restful.，然后导入带有idea的项目，执行SwaggerRestfulApplication.java。如果没有报告错误，则项目成功构建。

3.pom导入swagger2的依赖jar包

& lt！-用于JSON API文档生成->:

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency>​<!--用于文档界面展示--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

其中jar包springfox-swagger2用于生成JSON API文档，spring fox-swag-ui用于生成API文档接口。其他版本见https://mvnrepository . com/artifact/io . springfox/springfox-swag 2和https://mvnrepository . com/artifact/io . springfox/springfox-swag-ui

5.编写控制器和测试模型(测试控制器和测试)

编写测试的数据模型

package com.mage.swagger_restful.model;​public class Test {private Integer id;private String content;private Integer isValid;​public Integer getId() {return id;}​public void setId(Integer id) {this.id = id;}​public String getContent() {return content;}​public void setContent(String content) {this.content = content;}​public Integer getIsValid() {return isValid;}​public void setIsValid(Integer isValid) {this.isValid = isValid;}}基于Restful规则，编写一组测试的API接口：package com.mage.swagger_restful.controller;​import org.springframework.web.bind.annotation.*;​@RestController@RequestMapping("test")public class TestController {​@GetMapping("")public String list() {return "查询列表数据!";}​@GetMapping("{id}")public String find(@PathVariable Integer id) {return String.format("根据主键查询数据: %d", id);}​@PostMapping("")public String add() {return "插入数据!";}​@PutMapping("{id}")public String update(@PathVariable Integer id) {return String.format("根据主键更新一条记录: %d", id);}​@DeleteMapping("{id}")public String delete(@PathVariable Integer id) {return String.format("根据主键删除记录: %d", id);}}

因为界面是基于Restful编写的(本文不讨论Restful编写规范)，所以单纯使用浏览器输入，比如模拟post、put或delete请求，是不可能测试界面的。这时候可以用一些浏览器插件比如postman或者rested进行测试。这样就要安装额外的工具，比较麻烦。同时，在工作中写好接口后，通常会写接口文档，所以聪明的代码农民会思考是否可以优化这个过程，让接口测试和接口文档编写变得简单快捷。于是霸气就产生了。

6.斯瓦格融入了代码

a)写斯瓦格的配置类

package com.mage.swagger_restful.config;​import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;​@Configuration@EnableSwagger2@ConditionalOnExpression("${swagger.enable:true}")public class SwaggerConfig {​@Beanpublic Docket createDocket(){​Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("码歌学院API").deion("码歌学院相关接口API文档").version("1.0").build()).select().apis(RequestHandlerSelectors.basePackage("com.mage")).paths(PathSelectors.any()).build();return docket;}​}

其中，@ enableswager2打开swage 2函数，是swage 2的一个注释。@ conditiona expression(" $ { swagger . enable:true } ")仅在swag时启用swagger2。配置文件中的enable为true，这是spring boot的一个注释，便于区分在不同的环境中是否启用了swagger2。

b)修改应用程序.属性

swagger.enable = true

c)修改测试实体模型和测试控制器，添加与Swagger对应的注释

修改测试实体模型:

package com.mage.swagger_restful.model;​import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;​@ApiModel(deion = "测试模型实体")public class Test {@ApiModelProperty(name = "id", value = "主键", hidden = true)private Integer id;@ApiModelProperty(name = "content", value = "测试内容")private String content;@ApiModelProperty(name = "isValid", value = "是否有效0=无效，1=有效", hidden = true)private Integer isValid;​public Integer getId() {return id;}​public void setId(Integer id) {this.id = id;}​public String getContent() {return content;}​public void setContent(String content) {this.content = content;}​public Integer getIsValid() {return isValid;}​public void setIsValid(Integer isValid) {this.isValid = isValid;}}

其中:

@ ApiModel(deion = " test model entity ")作用于参数实体或响应实体，deion代表描述信息；

@ apimodelproperty (name = "id "，value = "primary key "，hidden = true)作用于实体属性，标记属性名和描述内容。name表示属性名称，value表示属性内容，hidden默认为false。

要修改测试控制器:

package com.mage.swagger_restful.controller;​import com.mage.swagger_restful.model.Test;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import org.springframework.web.bind.annotation.*;​@RestController@RequestMapping("test")@Api(tags = "测试API接口")public class TestController {​@GetMapping("")@ApiOperation(value="获取列表数据", notes="获取列表下测试数据")public String list() {return "查询列表数据!";}​@GetMapping("{id}")@ApiOperation(value="获取ID数据", notes="根据ID获取某条测试数据")@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)public String find(@PathVariable Integer id) {return String.format("根据主键查询数据: %d", id);}​@PostMapping("")@ApiOperation(value="新增数据")@ApiParam(name = "test", value = "添加的测试模型实体")public String add(@RequestBody Test test) {return "插入数据!";}​@PutMapping("{id}")@ApiOperation(value="更新数据", notes="根据ID更新测试数据")@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)public String update(@PathVariable Integer id, @ApiParam(name = "test", value = "更新的测试模型实体") @RequestBody Test test) {return String.format("根据主键更新一条记录: %d", id);}​@DeleteMapping("{id}")@ApiOperation(value="删除数据", notes="根据ID删除测试数据")@ApiImplicitParam(name = "id", value = "主键id", paramType = "path", required = true)public String delete(@PathVariable Integer id) {return String.format("根据主键删除记录: %d", id);}}

其中:

@Api(tags = "test API interface ")标记控制器类做什么，tags表示分类；

@ApiOperation(value=“获取列表数据”，notes=“获取列表下的测试数据”)标记控制器下的方法，表示这个接口做什么，value是解释函数，notes详细解释；

@ apimplicit param(name = " id "，value = "primary key id "，paramType = "path "，required = true)标记参数，name为参数名，value为参数描述，paramType为参数类型:path (path参数)、query (query参数)、Body(请求体参数)、header(请求头参数)、form(表单提交参数)，require表示是否为必选项，默认值为false

@ApiParam(name = "test "，value = "updated test model entity ")与@ApiImplicitParam相似，标记参数，但不同的是:

对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。ApiParam只需要较少的属性，与swagger ui配合更好。

7.浏览器输入地址:http://localhost:8080/swag-ui . html

点击测试应用编程接口进行测试:

8.注意

如果使用swagger2.9.0，会有bug，比如我修改了TestController中的find方法。

旧方法:

新方法:

此时如果启动，访问swag ui时会出现bug:

这是dataType转换中的一个错误，因为我将id设置为int类型，默认情况下swag给出字符串空，所以它会提示一个错误。有两种解决方案，第一种是不写数据类型，第二种是升级swag-annotations和models jar包:

a)排除已经依赖于它的swagger注释和模型jar包

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version><exclusions><exclusion><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId></exclusion><exclusion><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId></exclusion></exclusions></dependency>

引进新的罐子包装

<dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.5.21</version></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.21</version></dependency>

这个可以完美解决！