文章目录
前言
在日常开发中,写接口文档是我们必不可少的,而Knife4j就是一个接口文档工具,可以看作是Swagger的升级版,但是界面比Swagger更好看,功能更丰富。
一、SpringBoot版本对应的Knife4j版本
首先,确保您了解您的项目所使用的Spring Boot版本。以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐:
本文以为SpringBoot3为例:
- Spring Boot 3 只支持OpenAPI3规范
- Knife4j提供的starter已经包含springdoc-openapi的jar,开发者需注意避免jar包冲突
- JDK版本必须 >= 17
二、使用步骤
1. 导入knife4j-openAPI3依赖
代码如下:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
2.配置application.yml文件
代码如下:
注意:只需要修改packages-to-scan,设置为自己controller文件下的路径
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan: org.example.controller
#knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
production: false
3. controller类中使用注解@Tag、@Operation和@RequestParam注解。
@Tag
用于说明或定义的标签,作用域controller类。
部分参数:
●name:名称
●description:描述
@Operation
描述 API 操作的元数据信息,作用域controller类中的方法。
●summary:简短描述
●description :更详细的描述
●hidden:是否隐藏
●tags:标签,用于分组API
●operationId:操作的唯一标识符,建议使用唯一且具有描述性的名称
●parameters:指定相关的请求参数,使用 @Parameter 注解来定义参数的详细属性。
●requestBody:指定请求的内容,使用 @RequestBody 注解來指定请求的类型。
●responses:指定操作的返回内容,使用 @ApiResponse 注解定义返回值的详细属
@Parameter
用于描述 API 操作中的参数 部分参数:
●name : 指定的参数名
●in:参数来源,可选 query、header、path 或 cookie,默认为空,表示忽略
○ParameterIn.QUERY 请求参数
○ParameterIn.PATH 路径参数
○ParameterIn.HEADER header参数
○ParameterIn.COOKIE cookie 参数
●description:参数描述
●required:是否必填,默认为 false
●schema :参数的数据类型。如 schema = @Schema(type = "string")
@Parameters(作用于controller方法)
包含多个 @Parameter 注解,指定多个参数。 代码参考: 包含了 param1 和 param2 两个参数
@Parameters({
@Parameter(
name = "param1",
description = "Parameter 1 description",
required = true,
in = ParameterIn.PATH,
schema = @Schema(type = "string")
),
@Parameter(
name = "param2",
description = "Parameter 2 description",
required = true,
in = ParameterIn.QUERY,
schema = @Schema(type = "integer")
)
})