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.springfoxgroupId>
       <artifactId>springfox-boot-starterartifactId>
       <version>3.0.0version>
   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.csdn.net/Gjw_java?type=blog", "[email protected]");
            return new ApiInfo(
                    "Spring Boot 集成 Swagger3 测试",
                    "Spring Boot 集成 Swagger3 测试接口文档",
                    "v1.0",
                    "https://blog.csdn.net/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 官方文档