Open API、Swagger、SpringFox、SpringDoc、knife4j介绍
先介绍下文档的一些名词,Open API、Swagger、SpringFox、SpringDoc、knife4j等
- Open API:OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护的,并被linux列为api标准,从而成为行业标准。
- Swagger:swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者,现在最新的版本为17年发布的 Swagger3(Open Api3)。国内绝大部分人还在用过时的swagger2(17年停止维护并更名为swagger3)。swagger2的包名为 ,而swagger3的包名为 .v3。
- SpringFox:SpringFox是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger2 集成到 Spring 中。后续的版本虽然支持了新的OpenAPI3标准,但内容还是仅有 swagger 2.0 相关的。
- SpringDoc:SpringDoc也是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger3 集成到 Spring 中,目前使用swagger3的项目,大多数使用的就是SpringDoc框架。
- knife4j:取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,可以看作是springDoc和SpringFox的扩展和增强
结论:到这里就清楚了OpenApi是一个规范标准,swagger实现了OpenApi标准。
为什么升级swagger3
Spring Boot 3 只支持OpenAPI3规范
注意事项;
- JDK版本必须 >= 17,因为版本也仅支持JDK17以上
- 旧版的Knife4j包记得删除,会有依赖冲突导致项目启动失败
- 使用 Spring Boot 3 请确保引入 springdoc-openapi 2.0+
升级流程
1. 配置修改
- 仅需引用该knife4j-openapi3-jakarta-spring-boot-starter依赖即可
<dependency>
<groupId></groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
- 但由于大部分情况下都是由swagger2.0升级上来的,所以会有旧注解爆红的问题,因此加入一个swagger的注解依赖,兼容旧代码。
<dependency>
<groupId></groupId>
<artifactId>swagger-annotations</artifactId>
</dependency>
- 注意:旧的依赖一定要删除,我使用的是版本,出现不兼容的情况,导致项目启动失败。
例如下面这个依赖就必须删除,否则访问文档会出现/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