spring-boot3.x整合Swagger 3 (OpenAPI 3) +knife4j

1.简介

OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后，Swagger规范正式更名为OpenAPI规范，并且根据OpenAPI规范的版本号进行了更新。因此，Swagger 3.0对应的就是OpenAPI 3.0版本，它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比，Swagger 3.0更加强调对RESTful API的支持和规范化，提供了更丰富和灵活的定义方式，并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。

1.1 Open API

OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

OpenAPI 3 Library for spring-boot (springdoc.org)

1.2 Swagger

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者

1.3 SpringFox

SpringFox 是一个成熟且广泛使用的库，它允许你通过注解描述 API 并生成符合 OpenAPI 规范（原 Swagger 规范）的文档。SpringFox 支持 Swagger 2.0 及其后继者 OpenAPI 3.0。

特点:

支持 Swagger 2.0 和 OpenAPI 3.0。
通过使用 Swagger 注解（如 @Api, @ApiOperation, @ApiModel, @ApiModelProperty 等）来描述 API。
提供了多种方式来自定义文档，包括通过代码或配置文件。
可以通过扫描类路径中的控制器类自动生成文档。
更新频率较低，最近几年维护活动减少。

1.4 SpringDoc

OpenAPI 3 Library for spring-boot (springdoc.org)

SpringDoc 是一个相对较新的替代方案，它专为 OpenAPI 3.0 设计，提供了对最新 OpenAPI 规范的全面支持。

特点:

主要关注 OpenAPI 3.0，对 OpenAPI 3.0 的支持更全面。
使用更简洁的注解（如 @Tag, @Operation, @Parameter 等）来描述 API。
更好的支持 Spring WebFlux，适合现代的响应式编程模型。
更频繁的更新和活跃的社区支持。
与 Spring Boot 的集成更加紧密，可以通过 Spring Boot 的自动配置特性简化设置过程。

1.5 Knife4j

Knife4jInsight(简单、方便的OpenAPI接口文档私有化聚合平台),地址：http://knife4j.nethttp://knife4j.net/

1.6 Swagger 3 (OpenAPI 3) 与swagger 2 区别

1.7 Swagger 3 (OpenAPI 3)注解详细介绍

（1）基本信息注解	描述	位置	属性
@OpenAPIDefinition	用于定义整个 API 文档的基本信息。	类、接口	`info`：指定 `@Info` 注解的对象，用于描述 API 文档的基本信息。
@Info	用于定义 API 文档的基本信息	类、接口。	title：API 的标题。 description：API 的描述。 version：API 的版本号。 termsOfService：服务条款的 URL。 contact：指定 @Contact 注解的对象，用于描述联系人信息。 license：指定 @License 注解的对象，用于描述许可证信息。
@Contact	用于定义 API 文档中的联系人信息。	类、接口	`name`：联系人的名称。 `url`：联系人的网址。 `email`：联系人的电子邮件地址。
@License	用于定义 API 文档中的许可证信息	类、接口。	`name`：许可证的名称。 `url`：许可证的网址。
（2）分组注解	描述	位置	属性
@Tag	用于给 API 分组，用途类似于为 API 文档添加标签。	方法、类、接口	`name`：分组的名称。
（3）请求方法注解	描述	位置	属性
@Operation	用于描述 API 的操作。	方法。	summary：操作的摘要信息。 description：操作的详细描述。 tags：指定 @Tag 注解的对象数组，用于将操作归类到特定的分组。 parameters：指定 @Parameter 注解的对象数组，用于描述操作的输入参数。 responses：指定 @ApiResponse 注解的对象数组，用于描述操作的响应结果。 requestBody：指定 @RequestBody 注解的对象，用于描述操作的请求体。
@Parameter	用于描述操作的输入参数。	方法	`name`：参数的名称。 `in`：参数的位置，可以是 `path`、`query`、`header`、`cookie` 中的一种。 `description`：参数的描述。 `required`：参数是否必需，默认为 `false`。 `schema`：指定 `@Schema` 注解的对象，用于描述参数的数据类型。
@RequestBody	用于描述操作的请求体	方法	`required`：请求体是否必需，默认为 `false`。 `content`：指定 `@Content` 注解的对象数组，用于描述请求体的内容。
@ApiResponse	用于描述操作的响应结果	方法	`responseCode`：响应的状态码。 `description`：响应的描述。 `content`：指定 `@Content` 注解的对象数组，用于描述响应的内容。
@Content	用于描述请求体或响应的内容	方法。	`mediaType`：内容的媒体类型。 `schema`：指定 `@Schema` 注解的对象，用于描述内容的数据类型。
@Schema	用于描述数据模型的属性。	方法、类、接口。	`title`：数据模型的标题。 `description`：数据模型的描述。 `type`：数据模型的类型。 `format`：数据模型的格式。
（4）路径注解	描述	位置	属性
@Path	用于定义路径参数。	方法	`value`：路径参数的名称。
@PathVariable	用于描述路径参数。	方法的参数	`value`：路径参数的名称。
@RequestParam	用于描述查询参数。	方法的参数。	`value`：查询参数的名称。 `required`：查询参数是否必需，默认为 `false`
@RequestBody	用于描述请求体。	方法的参数
（5）响应注解	描述	位置	属性
@ApiResponse	用于描述响应结果。	方法。	`responseCode`：响应的状态码。 `description`：响应的描述。 `content`：指定 `@Content` 注解的对象数组，用于描述响应的内容。
@Content	用于描述响应结果的内容	方法	`mediaType`：内容的媒体类型。 `schema`：指定 `@Schema` 注解的对象，用于描述内容的数据类型。
@Schema	用于描述数据模型的属性。	方法、类、接口。	`title`：数据模型的标题。 `description`：数据模型的描述。 `type`：数据模型的类型。 `format`：数据模型的格式。

2. 配置Knife4j

2.1 添加依赖

因为Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突。这里直接使用Knife4j

<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
     <version>4.4.0</version>
</dependency>

2.2 添加配置类

package com.zsh.test.swagger3test.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
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 io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.configuration.SpringDocConfiguration;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.boot.autoconfigure.AutoConfigureBefore;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Collections;

/**Knife4j整合swagger3
 * @author ZhaoShuhao
 * @data 2024/7/21 11:06
 */
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI springShopOpenApi() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("swagger3")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的测试接口文档")
                        // 接口文档版本
                        .version("1.0版本")
                        // 开发者联系方式
                        .contact(new Contact().name("zsh")
                                .email("1401969521@qq.com")));

    }
}

2.3 yml配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'zsh'
      paths-to-match: '/**'
      #生成文档所需的扫包路径，一般为启动类目录
      packages-to-scan: com.zsh.test.swagger3test


#knife4j配置
knife4j:
  #是否启用增强设置
  enable: true
  #开启生产环境屏蔽
  production: false
  #是否启用登录认证
  basic:
    enable: true
    username: admin
    password: 123456
  setting:
    language: zh_cn
    enable-version: true
    enable-swagger-models: true
    swagger-model-name: 用户模块

2.4 运行结果

路径：http://localhost:8080/doc.html