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

时间:2025-03-18 09:05:43

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的包名为 ,而swagger3的包名为 .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,因为版本也仅支持JDK17以上
  2. 旧版的Knife4j包记得删除,会有依赖冲突导致项目启动失败
  3. 使用 Spring Boot 3 请确保引入 springdoc-openapi 2.0+

升级流程

1. 配置修改

  1. 仅需引用该knife4j-openapi3-jakarta-spring-boot-starter依赖即可
        <dependency>
            <groupId></groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.3.0</version>
        </dependency>
  1. 但由于大部分情况下都是由swagger2.0升级上来的,所以会有旧注解爆红的问题,因此加入一个swagger的注解依赖,兼容旧代码。
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-annotations</artifactId>
        </dependency>
  1. 注意:旧的依赖一定要删除,我使用的是版本,出现不兼容的情况,导致项目启动失败。
    例如下面这个依赖就必须删除,否则访问文档会出现/swagger-resources接口404的情况:
        <dependency>
            <groupId></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.***.")
                // 第二种方式,匿名类实现的方式
                .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 注释的包是..

@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