Spring Boot 集成 Swagger 在线接口文档

标签：Spring Boot 接口 API 文档注解 import Swagger

今天看了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 格式的数据，非常便捷。

5. 总结

以上的内容便是我今天通过看Spring Boot 集成 Swagger 在线接口文档资料的总结，主要分析了 Swagger 简介以及优点以及 Spring Boot 集成 Swagger的配置，以及实践了实体类和接口类的使用。通过测试后，可以体验 Swagger 的使用。

标签：Spring,Boot,接口,API,文档,注解,import,Swagger
From： https://www.cnblogs.com/zhaokeke/p/17578251.html