SpringBoot整合Swagger3生成接口文档的示例代码

<!-- 导入SpringBoot集成Open API 3.0（Swagger3.0）的坐标 -->
<!-- 这个坐标它提供了一组注解和工具来集成Swagger UI和OpenAPI规范等-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

说明：上面的坐标内部导入了Swagger3.0的原生依赖（我们只需要在SpringBoot导入springdoc-openapi-ui即可）
    ①：io.swagger.core.v3:swagger-core:2.2.9
        Swagger Core是Swagger 3.x规范的核心实现，提供了一组Java API，用于生成和处理OpenAPI规范文件。
        它包括Swagger的核心功能，例如Model、Schema、Parameter、Response等，是构建Swagger API的必要条件。
    ②：io.swagger.core.v3:swagger-annotations:2.2.9
        Swagger Annotations是一个用于编写Swagger API文档的Java注解库，提供了一组注解，用于描述API元数据。
        例如，@Operation、@Parameter、@ApiResponse等注解基本包含了OpenAPI规范中的所有元素。
    ③：io.swagger.core.v3:swagger-models:2.2.9
        Swagger Models是Swagger 3.x规范的Java模型库，提供了一组Java模型类，用于表示OpenAPI规范文件。
        它包含了OpenAPI规范中的所有数据模型，例如PathItem、Operation、Parameter、Components等。

OpenAPI对象是Swagger中的核心类之一，用于描述整个API的结构和元数据。可以理解为一个API文档对象，其中包含了许多元素，如：
    ①：openapi属性：
        表示使用的 OpenAPI 规范版本（例如 3.0.1）。
    ②：info属性：
        表示API的基本信息，包括标题、版本号、描述、联系人等。使用Info类来创建这个对象。
    ③：servers属性：
        表示服务器地址或者URL模板列表。每个URL模板可以包含占位符，这些占位符可以被路径参数或者查询参数替换。
        使用Server类来创建这个对象。
    ④：paths属性（推荐使用注解方式，不推荐使用配置类配置）：
        表示API的所有路径和操作信息，使用PathItem类来描述每一个路径，使用Operation类来描述操作。
    ⑤：components属性：
        表示API的组件信息，比如响应模板、请求模板和安全方案等。
        使用Schema、Response、Parameter、SecurityScheme等类来创建这些对象。
    ⑥：tags属性：
        表示API的标签信息，用于对相似的操作进行分组。
    ⑦：addServersItem(Server server)方法：
        向servers属性中添加一个Server对象。
    ⑧：addPaths(String name, PathItem pathItem)方法：
        向paths属性中添加一个PathItem对象，其中name参数表示路径模板。
    ⑨：addTag(Tag tag)方法：
        向tags属性中添加一个Tag对象。
    ⑩：setComponents(Components components)方法：
        设置components属性的值。

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;

import java.util.HashMap;

/** 这是一个普通的Swagger配置文档，其中不包含API接口的配置（API接口的配置推荐使用注解方式）
 * @author Anhui OuYang
 * @version 1.0
 **/
@SpringBootConfiguration
public class SwaggerOpenApiConfig {

    /***
     * 构建Swagger3.0文档说明
     * @return 返回 OpenAPI
     */
    @Bean
    public OpenAPI customOpenAPI() {

        // 联系人信息(contact)，构建API的联系人信息，用于描述API开发者的联系信息，包括名称、URL、邮箱等
        // name：文档的发布者名称 url：文档发布者的网站地址，一般为企业网站 email：文档发布者的电子邮箱
        Contact contact = new Contact()
                .name("蚂蚁小哥")                             // 作者名称
                .email("xiaofeng@qq.com")                   // 作者邮箱
                .url("https://www.cnblogs.com/antLaddie/")  // 介绍作者的URL地址
                .extensions(new HashMap<String, Object>()); // 使用Map配置信息（如key为"name","email","url"）

        // 授权许可信息(license)，用于描述API的授权许可信息，包括名称、URL等；假设当前的授权信息为Apache 2.0的开源标准
        License license = new License()
                .name("Apache 2.0")                         // 授权名称
                .url("https://www.apache.org/licenses/LICENSE-2.0.html")    // 授权信息
                .identifier("Apache-2.0")                   // 标识授权许可
                .extensions(new HashMap<String, Object>());// 使用Map配置信息（如key为"name","url","identifier"）

        //创建Api帮助文档的描述信息、联系人信息(contact)、授权许可信息(license)
        Info info = new Info()
                .title("Swagger3.0 (Open API) 框架学习示例文档")      // Api接口文档标题（必填）
                .description("学习Swagger框架而用来定义测试的文档")     // Api接口文档描述
                .version("1.2.1")                                  // Api接口版本
                .termsOfService("https://example.com/")            // Api接口的服务条款地址
                .license(license)                                  // 设置联系人信息
                .contact(contact);                                 // 授权许可信息
        // 返回信息
        return new OpenAPI()
                .openapi("3.0.1")  // Open API 3.0.1(默认)
                .info(info);       // 配置Swagger3.0描述信息
    }
}

定义Swagger3.0配置信息注解：@OpenAPIDefinition （具体参考 io.swagger.v3.oas.annotations）注意：这个注解全局只能配置一个，主要配置文档信息和安全配置
    说明：用于描述整个API的元信息和全局属性，可以定义和描述，包括API版本、基本信息、服务器信息、安全方案等
    常用属性：
        ①：info：用于描述 API 基本信息的对象，包括标题、版本号、描述等属性；
        ②：servers：用于描述 API 服务的 URL 和配置信息的数组；
        ③：security：用于描述 API 安全方案的数组，其中每个安全方案包含多个安全需求；
        ④：tags：用于描述 API 标签的数组，每个标签包含名称、描述等属性；
        ⑤：externalDocs：用于描述外部文档链接的对象，包含描述和 URL 两个属性。

import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.servers.Server;
import org.springframework.boot.SpringBootConfiguration;

/**
 * @author Anhui OuYang
 * @version 1.0
 **/
@SpringBootConfiguration
@OpenAPIDefinition(
        // ## API的基本信息，包括标题、版本号、描述、联系人等
        info = @Info(
                title = "Swagger3.0 (Open API) 框架学习示例文档",       // Api接口文档标题（必填）
                description = "学习Swagger框架而用来定义测试的文档",      // Api接口文档描述
                version = "1.2.1",                                   // Api接口版本
                termsOfService = "https://example.com/",             // Api接口的服务条款地址
                contact = @Contact(
                        name = "蚂蚁小哥",                            // 作者名称
                        email = "xiaofeng@qq.com",                  // 作者邮箱
                        url = "https://www.cnblogs.com/antLaddie/"  // 介绍作者的URL地址
                ),
                license = @License(                                                // 设置联系人信息
                        name = "Apache 2.0",                                       // 授权名称
                        url = "https://www.apache.org/licenses/LICENSE-2.0.html"   // 授权信息
                )
        ),
        // ## 表示服务器地址或者URL模板列表，多个服务地址随时切换（只不过是有多台IP有当前的服务API）
        servers = {
                @Server(url = "http://192.168.2.235/demo/", description = "本地服务器一服务"),
                @Server(url = "http://192.168.2.236/demo/", description = "本地服务器二服务"),
        },
        externalDocs = @ExternalDocumentation(description = "更多内容请查看该链接", url = "xxx"))
public class SwaggerOpenApiConfig {
}

// 响应对象模型定义
@Data
@AllArgsConstructor
@Schema(description = "响应返回数据对象")
public class AjaxResult {

    @Schema(
            title = "code",
            description = "响应码",
            format = "int32",
            requiredMode = Schema.RequiredMode.REQUIRED
    )
    private Integer code;

    @Schema(
            title = "msg",
            description = "响应信息",
            accessMode = Schema.AccessMode.READ_ONLY,
            example = "成功或失败",
            requiredMode = Schema.RequiredMode.REQUIRED
    )
    private String msg;

    @Schema(title = "data", description = "响应数据", accessMode = Schema.AccessMode.READ_ONLY)
    private Object data;
}

// 模型定义示例：
@Data
@AllArgsConstructor
@Schema(title = "学生模型VO", description = "响应视图学生模型VO")
public class StudentVO {
    @Schema(name = "学生ID", description = "学生ID属性", format = "int64", example = "1")
    private Long id;            // 学生ID
    @Schema(name = "学生姓名", description = "学生姓名属性", example = "jack")
    private String name;        // 学生姓名
    @Schema(name = "学生年龄", description = "学生年龄属性", format = "int32", example = "24")
    private Integer age;        // 学生年龄
    @Schema(name = "学生地址", description = "学生地址属性", example = "安徽合肥")
    private String address;     // 学生地址
    @Schema(name = "学生分数", description = "学生分数属性", format = "double", example = "55.50")
    private Double fraction;    // 学生分数
    @Schema(name = "学生爱好", description = "学生爱好属性（List类型）",
            type = "array", example = "[\"玩\", \"写字\"]")
    private List<String> likes; // 学生爱好
}

// 接口定义
@RestController
@RequestMapping("/student")
@Tag(
        name = "StudentControllerAPI",
        description = "学生控制器接口",
        externalDocs = @ExternalDocumentation(
                description = "这是一个接口文档介绍",
                url = "https://www.cnblogs.com/antLaddie/"))
public class StudentController {

    /***
     * 根据ID查询学生信息（单条）
     * @param id 学生id
     * @return 返回一条数据
     */
    @Operation(
            summary = "根据Id查询学生信息",
            description = "根据ID查询学生信息，并返回响应结果信息",
            parameters = {
                    @Parameter(name = "id", description = "学生ID", required = true, example = "1")
            },
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "响应成功",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            title = "AjaxResul和StudentVO组合模型",
                                            description = "返回实体，AjaxResult内data为StudentVO模型",
                                            anyOf = {AjaxResult.class, StudentVO.class})
                            )
                    ),
                    @ApiResponse(
                            responseCode = "500",
                            description = "响应失败",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            title = "AjaxResul模型",
                                            description = "返回实体，AjaxResult内data为空",
                                            implementation = AjaxResult.class)
                            )
                    )
            }
    )
    @GetMapping("/findOne/{id}")
    public AjaxResult findOneStudent(@PathVariable(value = "id") Long id) {
        //模拟学生数据
        List<String> likes = Arrays.asList("抓鱼", "爬山", "写字");
        StudentVO studentVO = new StudentVO(id, "张三", 22, "安徽六安", 93.5, likes);
        return new AjaxResult(200, "成功", studentVO);
    }

    /***
     * 查询全部学生数据
     * @return 返回d条数据
     */
    @Operation(
            summary = "查询全部学生数据",
            description = "查询学生信息，并返回响应结果信息",
            parameters = {},
            deprecated = true,
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "响应成功",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            title = "AjaxResul和StudentVO组合模型",
                                            description = "返回实体，AjaxResult内data为" +
                                                    "StudentVO模型(并且StudentVO为集合)",
                                            anyOf = {AjaxResult.class, StudentVO.class})
                            )
                    )
            }
    )
    @GetMapping("/findAll")
    public AjaxResult findAllStudent() {
        //模拟学生数据
        List<String> likes = Arrays.asList("抓鱼", "爬山", "写字");
        StudentVO student1 = new StudentVO(1L, "张三", 22, "安徽六安", 93.5, likes);
        StudentVO student2 = new StudentVO(2L, "李四", 24, "安徽合肥", 99.5, likes);
        return new AjaxResult(200, "成功", Arrays.asList(student1, student2));
    }

    /***
     * 学生添加接口
     * @param studentDTO 学生DTO信息
     * @return 成功信息
     */
    @Operation(
            summary = "学生添加接口",
            description = "学生添加接口",
            parameters = {},
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    description = "学生信息DTO",
                    required = true,
                    content = {
                            @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(implementation = StudentDTO.class)
                            )
                    }
            ),
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "响应成功",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            title = "AjaxResul模型",
                                            description = "返回实体AjaxResult，并且Data为null",
                                            implementation = AjaxResult.class)
                            )
                    )
            }
    )
    @PostMapping("/saveStudent")
    public AjaxResult saveStudent(@RequestBody StudentDTO studentDTO) {
        System.out.println("成功添加数据：" + studentDTO);
        return new AjaxResult(200, "成功", null);
    }　

注解：@Tag 可以用于对接口进行分类和归类，便于开发人员组织和管理 API 文档
    具体属性：
        ①：name：表示标签的名称，必填属性，也得注意多个Controller上的name不要写一样的，这样就会把它们归类在一起。
        ②：description：表示标签的描述信息，非必填属性。
        ③：externalDocs：用于指定URL地址文档信息来追加描述接口的信息。非必填属性。
        示例：
            @Tag(
                    name = "StudentControllerAPI",
                    description = "学生控制器接口",
                    externalDocs = @ExternalDocumentation(
                            description = "这是一个接口文档介绍",
                            url = "https://www.cnblogs.com/antLaddie/"))

注解：@Operation用于对API操作（即方法）进行描述和标记。就是我们熟知的Controller下的一个个请求的方法上。
    具体可以参考 io.swagger.v3.oas.annotations。
    具体属性：
        ①：summary：用于简要描述API操作的概要。
        ②：description：用于详细描述API操作的描述信息。
        ③：parameters：用于指定API操作的参数列表，包括路径参数、请求参数、请求头部等。可以使用@Parameter注解进一步定义参数。
        ④：operationId：用于指定API操作的唯一标识符，可以用于生成客户端代码或文档等。
            说明：第三方工具使用operationId来唯一标识此操作。（具体我也没用过）
        ⑤：requestBody：用于定义API操作的请求体，可以使用@RequestBody注解进一步定义请求体。
            说明：这里的@RequestBody注解是@io.swagger.v3.oas.annotations.parameters.RequestBody包里的
        ⑥：responses：用于定义 API 操作的响应列表，包括成功响应和错误响应。可以使用@ApiResponse注解进一步定义响应。
        ⑦：security：用于对API操作进行安全控制，可以使用@SecurityRequirement注解进一步定义安全需求。（后面说）
        ⑧：deprecated：表示该API操作已经过时或不推荐使用。
        @Operation(
                summary = "根据Id查询学生信息",
                description = "根据ID查询学生信息，并返回响应结果信息",
                parameters = {
                        @Parameter(name = "id", description = "学生ID", required = true, example = "1")
                },
                responses = {
                        @ApiResponse(
                                responseCode = "200",
                                description = "响应成功",
                                content = @Content(
                                        mediaType = "application/json",
                                        schema = @Schema(
                                                title = "AjaxResul和StudentVO组合模型",
                                                description = "返回实体，AjaxResult内data为StudentVO模型",
                                                anyOf = {AjaxResult.class, StudentVO.class})
                                )
                        )
                }
            )

注解：@Parameter用于描述HTTP请求的参数信息，它是一个Parameter[]类型的数组，每个元素表示一个请求参数；
    具体参考：io.swagger.v3.oas.annotations；它是一个注解，和Parameter类一样，只不过一个是注解一个是类的方式
        ①：name：参数名称。
        ②：in：参数位置，可以是 query、header、path、cookie 等。
        ③：description：参数描述。
        ④：required：参数是否必须，默认为 false。
        ⑤：deprecated：参数是否已过时，默认为 false。
        ⑥：allowEmptyValue：是否允许空值，默认为false。
        ⑦：style：参数的序列化风格，可以是 "matrix"、"label"、"form"、"simple"、
            "spaceDelimited"、"pipeDelimited"、"deepObject"；
        ⑧：explode：当参数值是对象或数组时，是否将其展开成多个参数，默认为 false。
        ⑨：schema：参数类型和格式的定义，通常使用@Schema注解。（下面介绍）
        ⑩：example：参数值的示例；
        示例：
            parameters = {
                    @Parameter(name = "id", in = ParameterIn.PATH, description = "学生ID",
                            required = true, example = "1")
            },

注解：@Schema 是用于描述数据模型的基本信息和属性，具体可以参考“io.swagger.v3.oas.annotations.media”
    具体属性：
        ①：description：用于描述该类或属性的作用。
        ②：name：指定属性名。该属性只对属性有效，对类无效。
        ③：title：用于显示在生成的文档中的标题。
        ④：requiredMode：用于指定该属性是否必填项。枚举Schema.RequiredMode内可选值如下：
            默认AUTO：可有可无；REQUIRED：必须存在此字段(会加红色*)；NOT_REQUIRED：不需要存在此字段
        ⑤：accessMode：用于指定该属性的访问方式。
            包括AccessMode.READ_ONLY（只读）、AccessMode.WRITE_ONLY（只写）、AccessMode.READ_WRITE（读写）
        ⑥：format：用于指定该属性的数据格式。例如：日期格式、时间格式、数字格式。
        ⑦：example：为当前的属性创建一个示例的值，后期测试可以使用此值。
        ⑧：deprecated：用于指定该属性是否为已过时的属性，默认为false。
        ⑨：defaultValue：用于指定该属性的默认值。
        ⑩：implementation：用于显示为该类或属性引入具体的实体路径，这代表当前指定的类或者属性将参考引入的实体。
            就是说有个实体类，这个类里面有个teacher属性，这时里面的teacher属性可以指定具体的实体类，如下：
            public class Student {
                ...
                @Schema(description = "老师信息",implementation = Teacher.class)
                private Teacher teacher;
                ...
            }
    其它属性：
        ①：type：用于指定数据类型（Data Type）或者元素类型（Element Type）
            基本类型：取值为相应的 Java 类型名，例如 int、long、float、double、boolean 等。
            包装类型：与基本类型相同，取值为相应的Java包装类型名，例如Integer、Long、Float、Double、Boolean等。
            字符串类型：取值为string。
            数组类型：取值为 array。对于数组类型，还可以使用 schema 属性指定其元素类型的 Schema 信息。
            对象类型：不用指定type，可以通过implementation属性引入。
            枚举类型：取值为enum。对于枚举类型，还需要使用enumAsRef属性指定是否将其定义为一个独立的引用类型。
            其它类型：不用指定type，可以通过implementation属性引入。

@Schema注解：提供了四个属性来描述复杂类型，分别是allOf、anyOf、oneOf和not。
    这四个属性可以用于组合不同的JSON Schema以描述一个复杂类型，具体如下：
    ①：allOf: 表示当前schema是多个其它schema的并集。
        例如，如果一个Java类型同时实现了两个接口，那么可以使用allOf来表示这个Java类型继承了这两个接口的所有属性和方法。
    ②：anyOf: 表示当前schema可以匹配其中任意一个schema，其本身也是一个组合体，可以嵌套使用。
        例如，一个返回类型可能是多个Java类型中的任意一个，可以使用anyOf来描述这种情况。
    ③：oneOf: 表示当前schema只能匹配其中一个schema，其本身也是一个组合体，可以嵌套使用。
        例如，一个Java类型只能是多个子类型中的任意一个，可以使用oneOf来描述这种情况。
    ④：not: 表示当前Schema不能匹配某个schema。
        例如，一个Java类型不能是某个子类型，可以使用not来描述这种情况。
    但是总感觉这个Swagger无法满足我特定要求的实体，具体解决如下：
        比如我现在有个AjaxResult类（code，msg，data），其中data为Object或其它类型，这时我返回的数据里data为其它类型的
        实体，所以我这里不理解如何返回的实体中，通过点击data而显示另外实体，我只能通过anyOf方式来实现（加上注解）
        @ApiResponse(
                responseCode = "200",
                description = "响应成功",
                content = @Content(
                        mediaType = "application/json",
                        schema = @Schema(
                                description = "返回实体，AjaxResult内data为StudentVO模型",
                                anyOf = {AjaxResult.class, StudentVO.class})
                )
        )

/**
 * 老师接口描述
 *
 * @author Anhui OuYang
 * @version 1.0
 **/
public class InterfaceDescriptionConfig {

    /***
     * get方式保存老师信息接口
     * @return PathItem
     */
    public static PathItem addTeacher() {
        //=====================创建字段描述信息（老师类描述）如：TeacherDTO=====================
        Schema id = new IntegerSchema().format("int64").description("老师ID");
        Schema name = new StringSchema().minLength(2).maxLength(5).example("张三").description("老师姓名");
        Schema age = new IntegerSchema().format("int32").maximum(new BigDecimal("99"))
                .minimum(new BigDecimal("1")).example("23").description("老师年龄");
        Schema birthday = new DateSchema().format("date").example("2023-12-12").description("老师生日");
        Schema address = new StringSchema().minLength(2).maxLength(9).example("安徽省").description("老师地址");
        Schema salary = new NumberSchema().format("bigDecimal").maximum(new BigDecimal("99999.99"))
                .minimum(new BigDecimal("100.00")).example("6500.50").description("老师工资");
        Schema fraction = new NumberSchema().format("double").maximum(new BigDecimal("99.99"))
                .minimum(new BigDecimal("10.00")).example("25.3").description("老师评分");
        Schema likes = new ArraySchema().minItems(1).maxItems(10).description("这是一个爱好数组");
        Schema isHeadmaster = new BooleanSchema().example(true).description("是否是班主任");
        Schema schema = new ObjectSchema().description("老师对象属性")
                .addProperty("id", id).addProperty("name", name).addProperty("age", age)
                .addProperty("birthday", birthday).addProperty("address", address)
                .addProperty("salary", salary).addProperty("fraction", fraction)
                .addProperty("likes", likes).addProperty("isHeadmaster", isHeadmaster);
        //=====================响应字段描述信息（返回类描述）如：AjaxResult=====================
        Schema resultSchema = new ObjectSchema().description("响应信息对象")
                .addProperty("code", new IntegerSchema().example("200").description("响应码"))
                .addProperty("msg", new StringSchema().example("成功").description("响应信息"))
                .addProperty("data", schema);


        //设置响应头信息，可以设置系统响应头，也可以设置自定义响应头，具体声明，前端好获取指定响应头信息
        HashMap<String, Header> headers = new HashMap<>();
        headers.put("my-header1", new Header().description("测试响应头1").schema(new StringSchema()));
        headers.put("my-header2", new Header().description("测试响应头2").schema(new StringSchema()));
        headers.put("my-header3", new Header().description("测试响应头3").schema(new StringSchema()));
        // 设置响应信息
        ApiResponses apiResponses = new ApiResponses()
                .addApiResponse("200", new ApiResponse().description("响应成功信息").headers(headers)
                        .content(new Content().addMediaType("application/json",
                                new MediaType().schema(resultSchema))))
                .addApiResponse("500", new ApiResponse().description("响应失败"));
        // 设置请求信息
        RequestBody requestBody = new RequestBody()
                .content(new Content().addMediaType("application/json",
                        new MediaType().schema(schema)));

        // 设置请求URL后缀参数信息（可以添加多个）  接口描述
        List<Parameter> parameters = new ArrayList<>();
        Parameter sign = new Parameter()
                .name("sign")                       // 设置参数名称
                .description("URL参数标记信息")       // 设置描述
                .required(false)                    // 是否必传
                .in("path")                         // 参数信息参数位置（当前在URL路径后）
                .schema(new StringSchema())         // 参数类型
                .example("tx117839");               // 示例数据
        parameters.add(sign);
        // 设置当前接口描述信息
        Operation operation1 = new Operation()
                .operationId("addTeacher")
                .description("这是一个添加老师信息的接口")
                .requestBody(requestBody)
                .parameters(parameters)
                .responses(apiResponses);
        // 设置接口路径信息及请求方式（这里我设置了一个post请求的接口）
        return new PathItem().post(operation1).description("POST请求");
    }
}

接口及模型的描述（使用定义类的方式）

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Paths;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;

/**
 * @author Anhui OuYang
 * @version 1.0
 **/
@SpringBootConfiguration
public class SwaggerOpenApiConfig1 {

    /***
     * 构建Swagger3.0文档说明
     * @return 返回 OpenAPI
     */
    @Bean
    public OpenAPI customOpenAPI() {

        // 配置Info信息 ... 

        //通过Paths可以配置多组接口信息(Paths接收PathItem，这里的每个PathItem我抽取方式出去了)
        Paths paths = new Paths();
        paths.put("根据传入的老师信息进行数据保存", InterfaceDescriptionConfig.addTeacher());

        // 返回信息
        return new OpenAPI()
                .openapi("3.0.1")  // Open API 3.0.1(默认)
                .paths(paths)
                .info(null);       // 配置Swagger3.0描述信息
    }
}

接口信息的绑定到Swagger中

注解权限设置：@SecurityScheme （具体参考io.swagger.v3.oas.annotations.security）
    说明：用于定义API的安全方案。通过使用@SecurityScheme注解，我们可以为API定义多种安全方案，并指定每种方案的相关属性，
    例如认证类型、授权URL、令牌URL、作用域等。
    常用属性：
        ①：name：
            安全方案的名称；
        ②：type：
            认证类型，具体包含如下：SecuritySchemeType.API_KEY（API密钥）、SecuritySchemeType.HTTP（HTTP认证）、
                SecuritySchemeType.OAUTH2（OAuth2.0 认证）等；
        ③：description：
            安全方案的描述信息；
        ④：in：
            仅在使用API密钥认证时适用，表示API密钥的位置，包括如下：
                ApiKeyLocation.HEADER（HTTP 头部）、ApiKeyLocation.COOKIE（Cookie）等
        ⑤：scheme：
            仅在使用HTTP认证时适用，表示认证方案，例如HTTP Authentication Scheme.Basic（Basic 认证）；
            防止客户端需要在请求头部中添加一个包含用户名和密码的 Base64 编码字符串，并以 "Basic " 开头，如：
            Authorization: Basic YWRtaW46MTIzNDU2
        ⑥：bearerFormat：
            仅在使用 Bearer Token 认证时适用，表示 Bearer Token 的格式；
        ⑦：flows：
            仅在使用OAuth2.0认证时适用，表示OAuth2.0的认证流程，包括@OAuthFlows.authorizationCode、
            @OAuthFlows.clientCredentials、@OAuthFlows.password 和 @OAuthFlows.implicit等。
    示例：(可以在我们自定义的SwaggerOpenApiConfig内设置权限认证)
        @SecurityScheme(
            name = "JWT-test",                   // 认证方案名称
            type = SecuritySchemeType.HTTP,      // 认证类型，当前为http认证
            description = "这是一个认证的描述详细",  // 描述信息
            in = SecuritySchemeIn.HEADER,        // 代表在http请求头部
            scheme = "bearer",                   // 认证方案，如：Authorization: bearer token信息
            bearerFormat = "JWT")                // 表示使用 JWT 格式作为 Bearer Token 的格式

当前在自定义的SwaggerOpenApiConfig类上面设置了两种权限校验方式，如下：
@SecurityScheme(
        name = "JWT-test",                   // 认证方案名称
        type = SecuritySchemeType.HTTP,      // 认证类型，当前为http认证
        description = "这是一个认证的描述详细",  // 描述信息
        in = SecuritySchemeIn.HEADER,        // 代表在http请求头部
        scheme = "bearer",                   // 认证方案，如：Authorization: bearer token信息
        bearerFormat = "JWT")                // 表示使用 JWT 格式作为 Bearer Token 的格式
@SecurityScheme(
        name = "X-API-KEY",
        type = SecuritySchemeType.APIKEY,
        description = "这是一个认证的描述详细",
        in = SecuritySchemeIn.HEADER,
        scheme = "bearer")

设置全部接口描述都有指定的一种校验方式：
    在@OpenAPIDefinition注解里的security属性设置校验方式
    @OpenAPIDefinition(   
        ....
        security = @SecurityRequirement(name = "JWT-test")
    )
设置指定接口描述有指定的一种校验方式：
    在@Operation注解里的security属性设置校验方式
    @Operation(   
        ....
        security = @SecurityRequirement(name = "JWT-test")
    )