Spring Boot 2.7.5 整合 Swagger 3 实现可交互的后端接口文档

前言

问: 什么是 OpenAPI?

答: OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。

问: 什么是 Swagger?

答: Swagger 是一组围绕 OpenAPI 规范构建的开源工具，可以帮助您设计、构建、记录和使用 REST API。

主要的Swagger工具包括：

• Swagger Editor: 基于浏览器的编辑器，可以在其中编写 OpenAPI 定义。
• Swagger UI: 将 OpenAPI 定义呈现为交互式文档。
• Swagger Codegen: 从 OpenAPI 定义生成调用代码。
• Swagger Editor Next (beta): 基于浏览器的编辑器，您可以在其中编写和查看 OpenAPI 和 AsyncAPI 定义。
• Swagger Core: 用于创建、使用和使用 OpenAPI 定义的 Java 相关库。
• Swagger Parser: 用于解析 OpenAPI 定义的独立库
• Swagger APIDom: 提供单一的统一结构，用于跨各种描述语言和序列化格式描述 API。

集成

1. 初始 Spring Boot 项目
2. pom.xml 引入依赖

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   </dependency>
   

3. 编写 SwaggerConfig 配置类

   package com.example.demo.config;
   
   import org.springframework.beans.factory.annotation.Value;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.oas.annotations.EnableOpenApi;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   
   import java.util.ArrayList;
   
   /**
   * @Author: 高建伟
   * @Date: 2022/11/22
   * @Description: SwaggerConfig
   */
   @Configuration
   @EnableOpenApi
   public class SwaggerConfig {
   
       /**
       * 用于读取配置文件 application.properties 中 swagger 属性是否开启
       */
       @Value("${swagger.enabled}")
       private Boolean swaggerEnabled;
   
       @Bean
       public Docket docket() {
           return new Docket(DocumentationType.OAS_30)
                   .apiInfo(apiInfo())
                   // 是否开启swagger
                   .enable(swaggerEnabled)
                   .select()
                   // 过滤条件，扫描指定路径下的文件
                   .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                   // 指定路径处理，PathSelectors.any()代表不过滤任何路径
                   //.paths(PathSelectors.any())
                   .build();
       }
   
       private ApiInfo apiInfo() {
           /*作者信息*/
           Contact contact = new Contact("高建伟", "https://blog.youkuaiyun.com/Gjw_java?type=blog", "jianweigao19@163.com");
           return new ApiInfo(
                   "Spring Boot 集成 Swagger3 测试",
                   "Spring Boot 集成 Swagger3 测试接口文档",
                   "v1.0",
                   "https://blog.youkuaiyun.com/Gjw_java?type=blog",
                   contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList()
           );
       }
   }
   
   

4. 控制器中使用

   package com.example.demo.controller;
   
   import com.example.demo.entity.TestDict;
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiParam;
   import org.springframework.web.bind.annotation.*;
   
   /**
   * @Author: 高建伟
   * @Date: 2022/11/22
   * @Description:
   */
   @RestController
   @RequestMapping("/test")
   @Api(tags = "测试控制器")
   public class TestController {
   
       @ApiOperation("测试接口")
       @GetMapping("/hello")
       public String hello(){
           return "Hello world";
       }
   
       @ApiOperation("保存测试字典接口")
       @PostMapping("/saveDict")
       public String saveDict(@ApiParam(value = "id", required = true, example = "123456") @RequestBody TestDict testDict){
           return testDict.toString();
       }
   }
   

5. 实体中使用

   package com.example.demo.entity;
   
   import io.swagger.annotations.ApiModel;
   import io.swagger.annotations.ApiModelProperty;
   import lombok.AllArgsConstructor;
   import lombok.Data;
   import lombok.NoArgsConstructor;
   
   /**
   * @Author: 高建伟
   * @Date: 2022/11/22
   * @Description:
   */
   @Data
   @AllArgsConstructor
   @NoArgsConstructor
   @ApiModel("测试字典类")
   public class TestDict {
   
       @ApiModelProperty("主键")
       private String id;
       @ApiModelProperty("字典类型")
       private String dictType;
       @ApiModelProperty("字典值")
       private String dictValue;
       @ApiModelProperty("字典key")
       private String dictKey;
       @ApiModelProperty("备注")
       private String remark;
   }
   

访问

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

代码

点击获取测试代码

参考文献

Swagger 3.0 官方文档