Spring Boot 集成 Swagger 在线接口文档-526互联

今天看了Spring Boot 集成 Swagger 在线接口文档有关的很多东西，简单总结下我学习到的，以供之后复习参考。

学习目标：在学习过程中，主要掌握在 Spring Boot 中如何导入 Swagger 工具来展现项目中的接口文档。

1. Swagger 简介

1.1 Swagger解决的问题

随着互联网技术的发展，网站架构逐渐从传统的后端渲染转变为前后端分离，并且前端技术和后端技术越来越独立。在这种情况下，API文档变得至关重要，因为它成为前后端开发人员之间联系的桥梁。而Swagger工具就是解决这个问题的重要工具。

Swagger是一款开源的API文档工具，它可以自动生成、管理和展示在线的API接口文档。对于使用接口的人来说，开发人员只需要提供一个Swagger地址，他们就可以通过浏览器访问到在线的API接口文档。这样，不再需要开发人员手动编写和更新文档，大大减轻了文档维护的负担。同时，在Swagger的接口文档页面上，调用接口的人员还可以进行在线测试接口数据。这意味着他们可以直接在Swagger界面上输入参数、调用接口，并查看实时返回的结果。这对于前端和后端开发人员来说都非常方便，可以帮助他们快速调试和验证接口的正确性。

对于开发人员来说，Swagger不仅可以用来展示和测试接口，还可以在开发阶段使用。开发人员可以利用Swagger提供的在线接口文档界面，方便地测试接口数据，验证接口的逻辑和正确性。这样可以加快接口开发的速度，提高开发效率。

1.2 Swagger 官方

Swagger 官网为 https://swagger.io/

2.Swagger的依赖配置

Swagger 的 maven 依赖使用 Swagger 工具，必须要导入 maven 依赖，Spring Boot没有默认集成Swagger。

 1 <!--集成 Springfox Swagger --> 
 2 <dependency>  
 3 <groupId>io.springfox</groupId>  
 4 <artifactId>springfox-boot-starter</artifactId>  
 5 </dependency>  
 6 <!-- Swagger-Bootstrap-UI 的配置 --> 
 7 <dependency>  
 8 <groupId>io.springfox</groupId>  
 9 <artifactId>swagger-bootstrap-ui</artifactId>  
10 </dependency>

springfox-boot-starter 是 Springfox Swagger 的主要依赖项，它将自动导入其他必需的依赖项，并配置 Spring Boot 中的 Swagger 相关功能。这个依赖项提供了用于生成 Swagger 规范的注解和工具类。可以使用这些注解来描述你的 API，并通过运行应用程序来生成 API 文档。

其次，swagger-bootstrap-ui 是一个 Swagger UI 的增强版，提供了更好的用户体验和额外的功能。它基于 Swagger UI 构建，并添加了一些自定义样式和增强功能，比如支持 Markdown 文件渲染、权限控制等。使用该依赖项，可以在浏览器中以交互式方式查看和测试 API 文档。

3. Swagger 配置

在使用 Swagger 之前需要进行配置，Spring Boot 中对 Swagger 的配置非常方便，新建一个配置类，Swagger 的配置类上除了添加必要的@Configuration 注解外，还需要添加@EnableOpenApi 注解。

 1 package com.zhao.conf;
 2 
 3 import io.swagger.models.HttpMethod;
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.ApiInfoBuilder;
 7 import springfox.documentation.builders.PathSelectors;
 8 import springfox.documentation.builders.RequestHandlerSelectors;
 9 import springfox.documentation.oas.annotations.EnableOpenApi;
10 import springfox.documentation.service.ApiInfo;
11 import springfox.documentation.service.Contact;
12 import springfox.documentation.spi.DocumentationType;
13 import springfox.documentation.spring.web.plugins.Docket;
14 
15 @EnableOpenApi
16 @Configuration
17 /*
18 @EnableOpenApi 注解是用来启用 Springfox Swagger 的功能。在 Spring Boot 应用程序的配置类上添加该注解可以开启 Swagger 的自动配置，并生成 API 文档。
19 @Configuration 注解表示这是一个配置类，用于配置应用程序的各种组件。你可以将 @EnableOpenApi 注解添加到一个配置类中，从而将 Swagger 配置集成到应用程序中。
20 */
21 public class Swagger3Config {
22     /**
23      * 创建API应用
24      * apiInfo() 增加API相关信息
25      * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
26      * 本例采用指定扫描的包路径来定义指定要建立API的目录。
27      * swagger测试地址：http://localhost:8080/swagger-ui/index.html#/
28      * @return
29      */
30     @Bean
31     /*
32     @Bean 注解是 Spring Framework 提供的一个注解，用于将方法的返回对象注册为一个 Spring Bean。
33      在配置类中使用 @Bean 注解，可以定义并创建需要由 Spring 管理的 Bean 对象。
34      */
35     public Docket createRestApi() {
36         return new Docket(DocumentationType.OAS_30) // 使用Swagger3.0版本
37                 .enable(true)// 是否关闭在线文档，生产环境关闭
38                 .apiInfo(apiInfo())  // 指定构建api文档的详细信息的方法
39                 .select()  // 指定要生成api接口的包路径，这里把action作为包路径，生成controller中的所有接口
40                  .apis(RequestHandlerSelectors.basePackage("com.yan.action"))
41 //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))方法接口上添加了ApiOperation注解
42                 .paths(PathSelectors.any()).build()
43                 //针对应用的全局响应消息配置
44 //                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
45 //                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
46                 ;
47     }
48 
49     /**
50      * 创建该API的基本信息（这些基本信息会展现在文档页面中）
51      * 访问地址：http://项目实际地址/swagger-ui.html
52      * @return
53      */
54     private ApiInfo apiInfo() {
55         return new ApiInfoBuilder()
56                 .title("接口文档")        //设置页面标题
57                 .description("说明信息")  //设置接口描述
58                 .contact(new Contact("chenbai", "http://baidu.com", "cnblogs.com")) //设置联系方式
59                 .version("1.0")         //设置版本
60                 .build();               //构建
61     }
62 }

以上便是配置swagger的全部内容

下来，可以进行测试配置有没有生效

启动项目，在浏览器中输入 http://localhost:8080/test/swagger-ui/，即可看到 swagger 的接口页面，说明 Swagger 集成成功。

注意：有可能在配置 Swagger 时关不掉，是因为浏览器缓存引起的，清空一下浏览器缓存即可解决问题。

在配置类中加上

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

避免有时候出bug

具体说明：

在配置 Swagger（使用 Springfox Swagger）时，添加 spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER 是为了确保 Swagger 可以正确解析和显示 API 的路径。

默认情况下，Spring MVC 使用的是 Ant 风格的路径匹配策略。而 Swagger 在生成 API 文档时，需要解析并展示 API 的路径信息。如果不明确设置路径匹配策略，可能会导致 Swagger 无法正确解析一些路径的模式，进而影响 API 文档的生成和显示。

通过设置 spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER，你告诉 Spring MVC 显式地使用 Ant 风格的路径匹配器作为默认的路径匹配策略。这样，Swagger 就能正确地解析和处理 API 路径，确保生成准确的 API 文档。

4.Swagger 的使用

以上已经配置好Swagger，并且通过具体测试之后可以正常使用，在使用过程中，我们需要注意一些注解，重点要学会 Swagger 中常用的注解。

注解分别在分别在实体类上、Controller 类上以及 Controller 中的方法上，

接下来，就是要查看 Swagger 如何在页面上呈现在线接口文档的，并且结合 Controller 中的方法在接口中测试一下数据。

4.1 实体类上使用

 1 package com.zhao.domain;
 2 
 3 import io.swagger.annotations.ApiModel;
 4 import io.swagger.annotations.ApiModelProperty;
 5 import lombok.Data;
 6 
 7 import java.io.Serializable;
 8 @Data
 9 @ApiModel("针对前端的响应数据格式规范")
10 public class JsonResult implements Serializable {
11     @ApiModelProperty("是否处理成功，布尔类型数据")
12     private Boolean success;
13     @ApiModelProperty("响应消息信息，字符串类型")
14     private String message;
15     @ApiModelProperty("响应数据，对象类型")
16     private Object data;
17 
18     public static JsonResult success(String message, Object data) {
19         JsonResult res=new JsonResult();
20         res.setMessage(message);
21         res.setSuccess(true);
22         res.setData(data);
23         return res;
24     }
25 }

使用 @ApiModel 注解可以为实体类添加一个文档说明，并为该实体类提供一个可选的值（value）属性，用于指定该实体类在 API 文档中的名称或标题。使用 @ApiModelProperty 注解可以为实体类的属性添加一个文档说明，并为该属性提供一个可选的值（value）属性，用于指定该属性在 API 文档中的名称或标题。

4.2 Contorller上使用

 1 package com.zhao.action;
 2 
 3 import com.zhao.domain.JsonResult;
 4 import io.swagger.annotations.*;
 5 import org.springframework.web.bind.annotation.GetMapping;
 6 import org.springframework.web.bind.annotation.RequestMapping;
 7 import org.springframework.web.bind.annotation.RequestParam;
 8 import org.springframework.web.bind.annotation.RestController;
 9 @Api(tags="测试控制器")
10 @RestController
11 @RequestMapping("/test")
12 public class HelloController {
13     @ApiOperation("问候语测试")
14     @GetMapping("/hello")
15     @ApiImplicitParams({
16             @ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
17             @ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "111111")
18     })
19     public JsonResult hello(@ApiParam("用户名称") @RequestParam(value="username",required =true) String name){
20         String res="hello "+name+"!";
21         return JsonResult.success("处理完毕",res);
22     }
23 }

@Api 注解用于类上，表示标识这个类是 swagger 的资源。
@ApiOperation 注解用于方法，表示一个 http 请求的操作。
@ApiParam 注解用于参数上，用来标明参数信息。
使用 @ApiImplicitParams 注解可以为方法的参数添加一个或多个文档说明，并为这些参数提供详细的描述。通过使用 @ApiImplicitParam 注解，可以为方法的参数提供详细的文档说明。每个 @ApiImplicitParam 注解对应一个参数，其中 dataType 属性指定参数的数据类型，name 属性指定参数的名称，value 属性为参数提供了描述，required 属性指定参数是否必需，defaultValue 属性指定参数的默认值（如果有）。

在浏览器中可以看出 Swagger 页面对该接口的信息展示的非常全面，每个注解的作用以及展示的地方注意对应位置，通过页面即可知道该接口。

同时，开发人员可以直接使用该在线接口来测试数据的正确与否可以看出，直接在页面返回了 json 格式的数据，非常便捷。