Swagger学习与使用

1、概述

接口文档对于前后端开发人员都十分重要。尤其是近几年流行前后端分离后，接口文档又变成了重中之重。接口文档固然重要，但是由于项目周期等种种原因，后端开发人员经常出现无法及时更新接口文档，导致前端开发人员抱怨接口文档和实际情况不一致。很多前端开发人员会抱怨别人写的接口文档不规范，不及时更新。但是，当我们自己去写的时候，确实挺烦写接口文档的。如果接口文档可以实时动态生成就不会出现上面问题了，Swagger可以说是完美的解决上面的问题。

优点

1. 可以自动生成文档，只需要在接口中使用注解进行标注，就能生成对应的接口文档。
2. 自动更新文档，由于是动态生成的，所以如果我们修改了接口方法，文档也会自动对应修改(前提是注解也得到了更新)。这样就不会出现我们修改了接口，却忘记更新接口文档的情况。
3. 支持在线调试，Swagger提供了在线调试接口的功能。

缺点

1. Swagger不能创建测试用例，所以Swagger暂时不能帮我们处理完所有的事情。它只能提供一个简单的在线调试，如果你想存储你的测试用例，可以使用 Postman 或者 YAPI 这些支持创建测试用例的工具。
2. 需要遵循一些规范，它不是任意规范的。比如说，你可能会返回一个json数据，而这个数据可能是一个Map格式的，那么我们此时就不能标注这个Map格式的返回数据的每一个字段的说明，而如果它是一个实体类的话，我们可以通过标注类的属性来给返回字段加说明。再比如说，对于Swagger而言，不推荐在使用GET方式提交数据的时候还使用Body，仅推荐使用query参数、header参数或者路径参数（path），当然这个限制只适用于在线调试。
3. 没有接口文档更新管理，虽然一个接口更新完之后，可能不会关心旧版的接口信息，但你“可能"想看看旧版的接口信息，例如有些灰度更新发布的时候，可能还会关心旧版的接口。那么此时只能由后端去看看有没有注释留下了，所以可以考虑接口文档有大的更新的时候注释掉旧版的，然后编写下新版的。
4. 代码中存在注解依赖

2、springboot整合Swagger

添加Swagger的依赖

<!-- Swagger -->
<!-- Swagger依赖 -->
<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，我们必须对swagger进行配置，我们需要创建一个swagger的配置类，我们可以命名一个SwaggerConfig的配置类

package edu.xja.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documen