Swagger2的实现原理及应用

为什么使用Swagger2

1.由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。

2.随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

Swagger2相关依赖依赖

<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>

---

swagger基本配置

@Configuration注解代表上图SwaggerConfig类为配置类，启动boot后自动加载到容器中。

@EnableSwagger2则是用来启动Swagger支持，表示这是一个Spring Swagger的配置文件。

定义了一个Bean方法CustomDocket，Spring中名字并不重要，重要的是它返回一个Docket类，DocumentationType.SWAGGER_2作为Docket构造方法的参数，指定了所用的swagger版本2.0，而之后的apiInfo则是调用接下来的apiInfo函数，来创建Docket的信息。apiInfo函数采用ApiInfoBuilder类的build方法来创建ApiInfo类，build方法中所加入的参数将显示在swagger生成的Api接口文档中。

配置swagger-ui依赖中的Swagger2-Api文档页面的访问权限，重写WebMvcConfigurer类中的addResourceHandlers方法，允许指定资源访问，配置完成后即可访问生成的Api文档
---

swagger界面

登录之后界面如下:

---

swagger注解的使用

@Api:一般用于Controller中,用于接口分组。（如：@Api(value = "用户接口", description = "用户接口", tags = {"1.1.0"})

@ApiOperation:接口说明,用于controller控制层方法上。（如： @ApiOperation(value = "用户查询", notes = "根据ID查询用户信息")）

@ApiParam:接口说明,用于controller控制层方法参数上。（如： @ApiParam(name=“userId”,value = “用户ID", notes = "根据ID查询用户信息")）

@ApiModelProperty：实体参数说明,这里我通过Mybatis-generate逆向工程生成了swagger注解

效果演示:

---

测试结果成功了,返回了预期想要的参数，以上为spring boot结合swagger插件生成的API接口文档。