SpringBoot3.x版本将swagger2.0升级到swagger3.0，使用knife4j-openapi3-jakarta-spring-boot-starter依赖

Open API、Swagger、SpringFox、SpringDoc、knife4j介绍

先介绍下文档的一些名词，Open API、Swagger、SpringFox、SpringDoc、knife4j等

1. Open API：OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。
2. Swagger：swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）。swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。
3. SpringFox：SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。后续的版本虽然支持了新的OpenAPI3标准，但内容还是仅有 swagger 2.0 相关的。
4. SpringDoc：SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中，目前使用swagger3的项目，大多数使用的就是SpringDoc框架。
5. knife4j：取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案，可以看作是springDoc和SpringFox的扩展和增强

结论：到这里就清楚了OpenApi是一个规范标准，swagger实现了OpenApi标准。

为什么升级swagger3

Spring Boot 3 只支持OpenAPI3规范
注意事项；

1. JDK版本必须 >= 17，因为SpringBoot3.x版本也仅支持JDK17以上
2. 旧版的Knife4j包记得删除，会有依赖冲突导致项目启动失败
3. 使用 Spring Boot 3 请确保引入 springdoc-openapi 2.0+

升级流程

1. pom.xml配置修改

1. 仅需引用该knife4j-openapi3-jakarta-spring-boot-starter依赖即可

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

2. 但由于大部分情况下都是由swagger2.0升级上来的，所以会有旧注解爆红的问题，因此加入一个swagger的注解依赖，兼容旧代码。

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </dependency>

3. 注意：旧的依赖一定要删除，我使用的是springboot3.x版本，出现不兼容的情况，导致项目启动失败。
   例如下面这个依赖就必须删除，否则访问文档会出现/swagger-resources接口404的情况：

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

2. 配置文件修改：

springdoc:
	# get请求多参数时不需要添加额外的@ParameterObject和@Parameter注解
  default-flat-param-object: true
	# 启用swaggerUI
  swagger-ui:
    enabled: true
	# 启用文档，默认开启
  api-docs:
    enabled: true

3. swaggerConfig配置定义：

package com.skiffenergy.energycloud.config;

import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    /**
     * 文档首页概述
     *
     * @return
     */
    @Bean
    public OpenAPI globalOpenApi() {
        return new OpenAPI()
                .info(new Info().title("***系统")
                        .description("接口文档")
                        .version("3.0"));
    }

    /**
     * 接口分组
     *
     * @param operationCustomizer 定制参数对象
     * @return
     */
    @Bean
    public GroupedOpenApi defaultApi(OperationCustomizer operationCustomizer) {
        return GroupedOpenApi.builder()
                // 分组名称
                .group("public")
                // 接口包路径
                .packagesToScan("com.***.controller")
                // 第一种方式，使用带参构造声明接口定制参数
                .addOperationCustomizer(operationCustomizer)
                .build();
    }

    @Bean
    public GroupedOpenApi openapiApi() {
        return GroupedOpenApi.builder()
                // 分组名称
                .group("开放接口")
                // 接口包路径
                .packagesToScan("com.***.openapi.controller")
                // 第二种方式，匿名类实现的方式
                .addOperationCustomizer((operation, handlerMethod) ->
                        operation.addParametersItem(new HeaderParameter().name("x-auth-token").schema(new StringSchema())))
                .build();
    }

    /**
     * 声明定制参数的Bean对象
     *
     * @return
     */
    @Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> operation.addParametersItem(
                new Parameter()
                        // 在请求头中传递
                        .in(SecuritySchemeIn.HEADER.toString())
                        .required(true)
                        // 参数解释
                        .description("token 鉴权")
                        // 参数字段值
                        .name("Authorization"));
    }
}

4. 注解替换：

用 swagger 3 注释替换 swagger 2 注释（它已经包含在springdoc-openapi-ui依赖项中）。swagger 3 注释的包是io.swagger.v3.oas.annotations.

@Api → @Tag
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”)
@ApiParam → @Parameter
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”)

官网地址：swagger3.0