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

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 中进行配置

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

    @Bean
    public Docket swaggerInfo() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo());

        return docket;
    }

    private ApiInfo getApiInfo() {
        // 作者信息
        Contact contact = new Contact("Scorpions", "github.com/Wu-yikun", "w577159462@163.com");
        return new ApiInfo(
                "Swagger2?!!!",
                "Stay hungry",
                "v2.0",
                "gitee.com/Wu-Yikun",
                contact,
                "Apache 2.0",
                "www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
    
}

访问 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 扫描接口的一般流程：

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
	// 配置Swagger的Docket实例
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.apis()		// 指定扫描接口
            	.paths()	// 过滤路径
                .build();
    }
}

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

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

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

3.2.2 apis()

public class ApiSelectorBuilder {
  	private final Docket parent;
  	private Predicate<RequestHandler> requestHandlerSelector = ApiSelector.DEFAULT.getRequestHandlerSelector();
    ...
        
    public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) {
      requestHandlerSelector = and(requestHandlerSelector, selector);
      return this;
    }
    
    ...
}

观察以上 ApiSelectorBuilder.java 源码，得知 apis 方法可传入以下参数：

① RequestHandlerSelectors.none(): 全都不扫描

@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.apis(ReqeustHandlerSelectors.none())
                .build();
    }
}

② ReqeustHandlerSelectors.any(): 扫描全部

@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.apis(ReqeustHandlerSelectors.any())
                .build();
    }
}

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

@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.apis(ReqeustHandlerSelectors.any())
            	.apis(RequestHandlerSelectors.basePackage("com.one.swagger.controller"))
                .build();
    }
}

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

@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.apis(ReqeustHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .build();
    }
}

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

@Configuration
@EnableSwagger2		// 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.apis(ReqeustHandlerSelectors.withClassAnnotation(RestController.class))
                .build();
    }
}

综合实例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean("docket")
	public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                /**
                 * apis():指定扫描的接口
                 *   RequestHandlerSelectors:配置要扫描接口的方式
                 *       basePackage:指定要扫描的包
                 *       any:扫描全部
                 *       none:不扫描
                 *       withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
                 *       withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
                 */
                .apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
                .build();
    }
}

3.2.3 paths()

paths() 与 apis() 相似，使用 PathSelectors，这里不再赘述：

① PathSelectors.ant(): 过滤 Spring 的 AntPathMatcher 提供的 match 方法匹配的路径

@Configuration
@EnableSwagger2		// 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.paths(PathSelectors.ant("/hello/**"))
                .build();
    }
}

过滤 /hello/** 请求：

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

@Configuration
@EnableSwagger2		// 开启Swagger2
public class SwaggerConfig {
    @Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.paths(PathSelectors.regex("^/hello"))
                .build();
    }
}

过滤以 /hello 开头的请求：

③ PathSelectors.none()

④ PathSelectors.any()

综合实例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean("docket")
	public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                /**
                 * paths():过滤路径
                 *   PathSelectors:配置过滤的路径
                 *      any:过滤全部路径
                 *      none:不过滤路径
                 *      ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
                 *      regex:过滤指定路径:按照String的matches方法进行匹配
                 */
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }
}

3.3 配置 API 文档分组

上文有提及 Docket 对象中的 groupName 属性，groupName 用于设置 API 文档的分组，默认分组为 default。

可以为不同的分组配置不同的 Swagger 扫描接口！

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.none())
                .build()
                .groupName("X");      // 设置API文档为X组
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .paths(PathSelectors.regex("^/swagger"))
                .build()
                .groupName("Y");      // 设置API文档为Y组
    }
    
	@Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .paths()
                .build()
            	.groupName("Scorpions");	// 设置Swagger的API文档分组
    }
    
}

Scorpions 分组：

X 分组：

Y 分组：

3.4 配置是否启动 Swagger

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	@Bean("docket")
    public Docket getSwaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	// true表示启用swagger、false表示不启用swagger
                .enable(false)
                .select()
                .paths()
                .build();
    }
}

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

---

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

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

application-dev.yml:

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

application-pro.yml:

# 生产环境
server:
  port: 8082

application.properties:

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

SwaggerConfig.java:

@Configuration
@EnableSwagger2     // 开启Swagger2, 访问网址: http://localhost:8080/swagger-ui.html
public class SwaggerConfig {

	@Bean("docket")
    public Docket getSwaggerDocket(Environment environment) {

        // 设置启用Scorpions分组下的Swagger文档的环境列表
        Profiles profiles = Profiles.of("dev", "test", "otherEnv");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/hello/**"))
                .build()
                .groupName("Scorpions");
    }

    @Bean
    public Docket swaggerInfo(Environment environment) {

        // 仅在 dev、test 环境下启用Z分组的Swagger接口文档!
        Profiles profiles = Profiles.of("dev", "test");
        boolean flag = environment.acceptsProfiles(profiles);

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .groupName("Z");
        return docket;
    }
}

当前为开发环境：

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

4.1 实体类注释

4.1.1 编写实体类

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

User.java:

@ApiModel("用户实体类")     // 文档注释
public class User {
    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    // 属性设置为 public, 在 Swagger 中才可视
    @ApiModelProperty("姓名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

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

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

@RestController
public class HelloController {
    @GetMapping("/swagger1")
    public User getUser() {
        return new User("Scorpions_", "123456");
    }
}

4.1.3 测试访问

成功显示 Model 信息:

4.2 接口注释

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

示例1

@RestController
public class HelloController {
    @GetMapping("/swagger2")
    @ApiOperation("response返回错误")
    public User swagger2(@ApiParam("接口形参num") int num) {
        int i = num / 0;
        return new User();
    }
}

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

---

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

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

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

示例2

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

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

response 返回预期结果：