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)注解详细介绍

 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