前言

问: 什么是 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。

集成

初始 Spring Boot 项目

pom.xml 引入依赖

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

编写 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", "jianweigao19@163.com");
         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()
         );
     }
 }

控制器中使用

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();
    }
}

实体中使用

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