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 相关依赖

1. <dependencies>
2.     <!-- 引入web才能打开浏览器-->
3.     <dependency>
4.         <groupId>org.springframework.boot</groupId>
5.         <artifactId>spring-boot-starter-web</artifactId>
6.     </dependency>
8.     <!-- 引入Swagger2、SwaggerUI依赖 -->
9.     <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
10.     <dependency>
11.         <groupId>io.springfox</groupId>
12.         <artifactId>springfox-swagger2</artifactId>
13.         <version>2.9.2</version>
14.     </dependency>
15.     <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
16.     <dependency>
17.         <groupId>io.springfox</groupId>
18.         <artifactId>springfox-swagger-ui</artifactId>
19.         <version>2.9.2</version>
20.     </dependency>
21. </dependencies>

复制代码

2.2 编写 Controller

1. @RestController
2. public class HelloController {
4.     @RequestMapping("/hello")
5.     public String helloSwagger() {
6.         return "Hello Swagger!";
7.     }
9. }

复制代码

2.3 编写 Swagger 配置类

1. @Configuration
2. @EnableSwagger2     // 开启Swagger2
3. public class SwaggerConfig {
4. }

复制代码

2.4 访问接口文档

访问 http://localhost:8080/swagger-ui.html：

该 swagger-ui.html 界面是 Swagger 为我们提供的 UI 界面，可在引入的依赖中找到：

3. 配置 Swagger（SwaggerConfig.java）

Swagger 有自己的 Bean 实例：Docket
3.1 配置 Swagger ApiInfo 信息

只需要在 SwaggerConfig 配置类中添加包含 ApiInfo 类信息的 Docket Bean 实例，就可以配置 Swagger 信息：

这里我们点进 Docket 源码中检察，发现大部分属性已有默认值，仅有一个构造函数且需要传入 DocumentationType 实例：

DocumentationType.java 是什么？点击进入，这里有三个可供选择的值：

同时若想自定义 Swagger Api 信息，则需要传入 Swagger ApiInfo，如下为默认配置：

在 SwaggerConfig.java 中进行配置

1. @Configuration
2. @EnableSwagger2     // 开启Swagger2
3. public class SwaggerConfig {
5.     @Bean
6.     public Docket swaggerInfo() {
7.         Docket docket = new Docket(DocumentationType.SWAGGER_2)
8.                 .apiInfo(getApiInfo());
10.         return docket;
11.     }
13.     private ApiInfo getApiInfo() {
14.         // 作者信息
15.         Contact contact = new Contact("Scorpions", "github.com/Wu-yikun", "w577159462@163.com");
16.         return new ApiInfo(
17.                 "Swagger2?!!!",
18.                 "Stay hungry",
19.                 "v2.0",
20.                 "gitee.com/Wu-Yikun",
21.                 contact,
22.                 "Apache 2.0",
23.                 "www.apache.org/licenses/LICENSE-2.0",
24.                 new ArrayList<>()
25.         );
26.     }
27.    
28. }

复制代码

访问 http://localhost:8080/swagger-ui.html：

3.2 配置 Swagger 扫描接口

目前 Swagger 文档中有两个 Controller：

• 一个默认的 /error：
  

• 另有一个是我们自己写的 /hello 请求
  

   由于 @RequestMapping 未指定提交方式 method：以是 Swagger 文档中就会罗列出全部的 method 供选择，如: GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH
  

3.2.1 select()、build()

配置 Swagger 扫描接口的一般流程：

1. @Configuration
2. @EnableSwagger2     // 开启Swagger2
3. public class SwaggerConfig {
4.         // 配置Swagger的Docket实例
5.     @Bean("docket")
6.     public Docket getSwaggerDocket() {
7.         return new Docket(DocumentationType.SWAGGER_2)
8.                 .apiInfo(apiInfo())
9.                 .select()
10.                     .apis()                // 指定扫描接口
11.                     .paths()        // 过滤路径
12.                 .build();
13.     }
14. }

复制代码

Docket 中的 select() 返回 ApiSelectorBuilder 对象：

ApiSelectorBuilder 中的 build() 返回 Docket 对象，而 apis() 与 paths() 都返回 ApiSelectorBuilder 对象，可用于链式调用：

接下来介绍 apis() 与 paths() 的使用方法
3.2.2 apis()

1. public class ApiSelectorBuilder {
2.           private final Docket parent;
3.           private Predicate<RequestHandler> requestHandlerSelector = ApiSelector.DEFAULT.getRequestHandlerSelector();
4.     ...
5.         
6.     public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) {
7.       requestHandlerSelector = and(requestHandlerSelector, selector);
8.       return this;
9.     }
10.    
11.     ...
12. }

复制代码

观察以上 ApiSelectorBuilder.java 源码，得知 apis 方法可传入以下参数：
① RequestHandlerSelectors.none(): 全都不扫描

1. @Configuration
2. @EnableSwagger2  // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .apis(ReqeustHandlerSelectors.none())
10.                 .build();
11.     }
12. }

复制代码

② ReqeustHandlerSelectors.any(): 扫描全部

1. @Configuration
2. @EnableSwagger2  // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .apis(ReqeustHandlerSelectors.any())
10.                 .build();
11.     }
12. }

复制代码

③ RequestHandlerSelectors.basePackage(): 扫描指定包

1. @Configuration
2. @EnableSwagger2  // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .apis(ReqeustHandlerSelectors.any())
10.                     .apis(RequestHandlerSelectors.basePackage("com.one.swagger.controller"))
11.                 .build();
12.     }
13. }

复制代码

④ RequestHandlerSelectors.withMethodAnnotation(): 扫描方法上的注解

1. @Configuration
2. @EnableSwagger2  // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .apis(ReqeustHandlerSelectors.withMethodAnnotation(GetMapping.class))
10.                 .build();
11.     }
12. }

复制代码

⑤ RequestHandlerSelectors.withClassAnnotation(): 扫描类上的注解

1. @Configuration
2. @EnableSwagger2                // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .apis(ReqeustHandlerSelectors.withClassAnnotation(RestController.class))
10.                 .build();
11.     }
12. }

复制代码

综合实例：

1. @Configuration
2. @EnableSwagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.         public Docket docket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                 /**
10.                  * apis():指定扫描的接口
11.                  *   RequestHandlerSelectors:配置要扫描接口的方式
12.                  *       basePackage:指定要扫描的包
13.                  *       any:扫描全部
14.                  *       none:不扫描
15.                  *       withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
16.                  *       withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
17.                  */
18.                 .apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
19.                 .build();
20.     }
21. }

复制代码

3.2.3 paths()

paths() 与 apis() 相似，使用 PathSelectors，这里不再赘述：
① PathSelectors.ant(): 过滤 Spring 的 AntPathMatcher 提供的 match 方法匹配的路径

1. @Configuration
2. @EnableSwagger2                // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .paths(PathSelectors.ant("/hello/**"))
10.                 .build();
11.     }
12. }

复制代码

过滤 /hello/** 请求：

② PathSelectors.regex(): 过滤正则表达式指定的路径

1. @Configuration
2. @EnableSwagger2                // 开启Swagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                     .paths(PathSelectors.regex("^/hello"))
10.                 .build();
11.     }
12. }

复制代码

过滤以 /hello 开头的请求：

③ PathSelectors.none()
④ PathSelectors.any()
综合实例：

1. @Configuration
2. @EnableSwagger2
3. public class SwaggerConfig {
4.     @Bean("docket")
5.         public Docket docket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                 .select()
9.                 /**
10.                  * paths():过滤路径
11.                  *   PathSelectors:配置过滤的路径
12.                  *      any:过滤全部路径
13.                  *      none:不过滤路径
14.                  *      ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
15.                  *      regex:过滤指定路径:按照String的matches方法进行匹配
16.                  */
17.                 .paths(PathSelectors.ant("/hello/**"))
18.                 .build();
19.     }
20. }

复制代码

3.3 配置 API 文档分组

上文有提及 Docket 对象中的 groupName 属性，groupName 用于设置 API 文档的分组，默认分组为 default。
可以为差别的分组配置差别的 Swagger 扫描接口！

1. @Configuration
2. @EnableSwagger2
3. public class SwaggerConfig {
5.     @Bean
6.     public Docket docket1() {
7.         return new Docket(DocumentationType.SWAGGER_2)
8.                 .select()
9.                 .apis(RequestHandlerSelectors.none())
10.                 .build()
11.                 .groupName("X");      // 设置API文档为X组
12.     }
14.     @Bean
15.     public Docket docket2() {
16.         return new Docket(DocumentationType.SWAGGER_2)
17.                 .select()
18.                 .paths(PathSelectors.regex("^/swagger"))
19.                 .build()
20.                 .groupName("Y");      // 设置API文档为Y组
21.     }
22.    
23.         @Bean("docket")
24.     public Docket getSwaggerDocket() {
25.         return new Docket(DocumentationType.SWAGGER_2)
26.                 .apiInfo(apiInfo())
27.                 .select()
28.                 .paths()
29.                 .build()
30.                     .groupName("Scorpions");        // 设置Swagger的API文档分组
31.     }
32.    
33. }

复制代码

Scorpions 分组：

X 分组：

Y 分组：

3.4 配置是否启动 Swagger

Docket 对象通过 enable() 方法来配置 Swagger 是否启用。

1. @Configuration
2. @EnableSwagger2
3. public class SwaggerConfig {
4.         @Bean("docket")
5.     public Docket getSwaggerDocket() {
6.         return new Docket(DocumentationType.SWAGGER_2)
7.                 .apiInfo(apiInfo())
8.                     // true表示启用swagger、false表示不启用swagger
9.                 .enable(false)
10.                 .select()
11.                 .paths()
12.                 .build();
13.     }
14. }

复制代码

enable(false) 使得仅当前分组不启用 Swagger 文档，而其他分组仍然启用，若仅剩一个 group，则会出现如下的页面：

---

?? 若只希望 Swagger 在开发环境中启用，在生产环境中不启用（发布的时间当然不能暴露 Swagger 文档，不然造成外部可以随意调用接口）

• Environment 对象可作为参数由 Spring 容器自动传入
  
• 通过 environment.acceptsProfiles(profiles) 来判定是否处于自己设定的环境当中
  
• 将 flag 传入 enable() 方法的参数列表，如果处于自己设定的环境则开启 Swagger 接口文档
  

application-dev.yml:

1. # 开发环境下默认使用该配置文件(约定俗成的名字)
2. server:
3.   port: 8080

复制代码

application-pro.yml:

1. # 生产环境
2. server:
3.   port: 8082

复制代码

application.properties:

1. # 使得dev环境的配置生效: application-dev
2. spring.profiles.active=dev

复制代码

SwaggerConfig.java:

1. @Configuration
2. @EnableSwagger2     // 开启Swagger2, 访问网址: http://localhost:8080/swagger-ui.html
3. public class SwaggerConfig {
5.         @Bean("docket")
6.     public Docket getSwaggerDocket(Environment environment) {
8.         // 设置启用Scorpions分组下的Swagger文档的环境列表
9.         Profiles profiles = Profiles.of("dev", "test", "otherEnv");
10.         boolean flag = environment.acceptsProfiles(profiles);
12.         return new Docket(DocumentationType.SWAGGER_2)
13.                 .apiInfo(apiInfo())
14.                 .enable(flag)
15.                 .select()
16.                 .apis(RequestHandlerSelectors.any())
17.                 .paths(PathSelectors.ant("/hello/**"))
18.                 .build()
19.                 .groupName("Scorpions");
20.     }
22.     @Bean
23.     public Docket swaggerInfo(Environment environment) {
25.         // 仅在 dev、test 环境下启用Z分组的Swagger接口文档!
26.         Profiles profiles = Profiles.of("dev", "test");
27.         boolean flag = environment.acceptsProfiles(profiles);
29.         Docket docket = new Docket(DocumentationType.SWAGGER_2)
30.                 .apiInfo(getApiInfo())
31.                 .enable(flag)
32.                 .select()
33.                 .apis(RequestHandlerSelectors.any())
34.                 .build()
35.                 .groupName("Z");
36.         return docket;
37.     }
38. }

复制代码

当前为开发环境：

4. Swagger 接口注释&实体类注释

4.1 实体类注释

4.1.1 编写实体类

• @ApiModel：为实体类添加注释
  
• @ApiModelProperty：为实体类属性添加注释
  

User.java:

1. @ApiModel("用户实体类")     // 文档注释
2. public class User {
3.     public User() {
4.     }
6.     public User(String username, String password) {
7.         this.username = username;
8.         this.password = password;
9.     }
11.     // 属性设置为 public, 在 Swagger 中才可视
12.     @ApiModelProperty("姓名")
13.     public String username;
14.     @ApiModelProperty("密码")
15.     public String password;
17.     public String getUsername() {
18.         return username;
19.     }
21.     public void setUsername(String username) {
22.         this.username = username;
23.     }
25.     public String getPassword() {
26.         return password;
27.     }
29.     public void setPassword(String password) {
30.         this.password = password;
31.     }
32. }

复制代码

4.1.2 编写实体类对应的请求方法

编写完实体类后，我们还是无法在 Model 中看到 User 实体类信息，需在 HelloController 中新增一个返回 User 对象的请求方法：

1. @RestController
2. public class HelloController {
3.     @GetMapping("/swagger1")
4.     public User getUser() {
5.         return new User("Scorpions_", "123456");
6.     }
7. }

复制代码

4.1.3 测试访问

乐成表现 Model 信息:

4.2 接口注释

• @ApiOperation：为接口添加注释
  
• @ApiParam：为接口参数列表添加注释
  

示例1

1. @RestController
2. public class HelloController {
3.     @GetMapping("/swagger2")
4.     @ApiOperation("response返回错误")
5.     public User swagger2(@ApiParam("接口形参num") int num) {
6.         int i = num / 0;
7.         return new User();
8.     }
9. }

复制代码

接口及其形参列表上标有注释：

---

这里将 /swagger2 请求改成 POST 请求而不是 GET 请求：

1. @RestController
2. public class HelloController {
3.     @PostMapping("/swagger22")
4.     @ApiOperation("POST请求具备方法体, response返回错误")
5.     public User swagger2(@ApiParam("接口形参num") int num) {
6.         int i = num / 0;
7.         return new User();
8.     }
9. }

复制代码

请求效果符合预期的 500 错误：

示例2

1. // POST 表单才可以请求, 而 Swagger 在测试时会提供方法体, 仅需输入测试即可
2. // 注意传入的参数User实体类中必须要有 getter() 和 setter(), 方法才能正常赋值到形参user中!
3. @ApiOperation("Swagger3 POST 请求")
4. @PostMapping("/swagger3")
5. public User swagger3(@ApiParam("user参数, 必须设置属性的setter() & getter()") User user) {
6.     return user;
7. }

复制代码

填写完表单后会添加到方法体 body 中：

response 返回预期效果：

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。