Spring Boot（七）：Swagger 接口文档

1. Swagger 简介

1.1 Swagger 是什么？

Swagger 是一款 RESTful 风格的接口文档在线自动生成 + 功能测试功能软件。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。目标是使客户端和文件系统作为服务器以同样的速度（同步）更新文件的方法，参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，Swagger 是一款可以根据 resutful 风格生成的接口开发文档，API 文档与 API 同步更新，并且支持做测试的一款中间软件。

现在 Swagger 官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

Swagger Codegen：通过Codegen 可以将描述文件生成 html 格式和 wiki 形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过 jar 包，docker，node 等方式在本地化执行生成。也可以在后面的 Swagger Editor 中在线生成。

Swagger UI：提供了一个可视化的 UI 页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署 UI 项目。

Swagger Editor：类似于 markendown 编辑器的编辑 Swagger 描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector：感觉和 postman 差不多，是一个可以对接口进行测试的在线版的 postman。比在 Swagger UI 里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Springfox Swagger：Spring 基于 swagger 规范，可以将基于 SpringMVC 和 Spring Boot 项目的项目代码自动生成 JSON 格式的描述文件。本身不是属于 Swagger 官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

1.2 为什么要使用 Swagger？

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。

前端经常抱怨后端给的接口文档与实际情况不一致。

后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。

所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

总之，在这个前后端分离的时代，前后端联调会使得前后端开发人员无法做到即使协商，尽早解决。

发现了痛点就会去寻找更好的解决方案，所以 Swagger 接口文档就应运而生了。解决方案用的人多了，就成了标准的规范。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过 Swagger 衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新 Swagger 描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个 yml 或 json 格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。

所以作为 Java 届服务端的大一统框架 Spring，迅速将 Swagger 规范纳入自身的标准，建立了 Spring-swagger 项目，后面改成了现在的 Springfox。通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

1.2.1 对于后端开发人员来说

• 不用再手写 WiKi 接口拼大量的参数，避免手写错误
• 对代码侵入性低，采用全注解的方式，开发简单
• 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护

缺点：增加了开发成本，写接口还得再写一套参数配置

1.2.2 对于前端开发人员来说

• 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
• 联调方便，如果出问题，直接测试接口，实时检查参数和返回值，就可以快速定位是前端还是后端的问题

1.2.3 对于测试人员来说

• 对于某些没有前端界面 UI 的功能，可以用它来测试接口
• 操作简单，不用了解具体代码就可以操作

2. Spring Boot 集成 Swagger2（Getting Started）

2.1 导入 Swagger 相关依赖

<dependencies>
    <!-- 引入web才能打开浏览器-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 引入Swagger2、SwaggerUI依赖 -->
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

2.2 编写 Controller

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String helloSwagger() {
        return "Hello Swagger!";
    }

}

2.3 编写 Swagger 配置类

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
}