springboot3整合knife4j超详细教程(不带swagger2玩)_Java

1. 引入依赖

<dependency>
    <groupid>com.github.xiaoymin</groupid>
    <artifactid>knife4j-openapi3-jakarta-spring-boot-starter</artifactid>
    <version>4.4.0</version>
</dependency>

2. 配置文件

简短必要版

# 配置springdoc-openapi，用于文档化和访问api
springdoc:
  # 配置swagger ui的访问路径和排序方式
  swagger-ui:
    path: /swagger-ui.html  # swagger ui的访问路径
    tags-sorter: alpha      # 按字母顺序排序标签
    operations-sorter: alpha  # 按字母顺序排序操作
  # 配置api文档的访问路径
  api-docs:
    path: /v3/api-docs  # api文档的访问路径
  # 配置api分组，用于组织和管理api
  group-configs:
    - group: 'default'   # api分组名称
      paths-to-match: '/**'  # 匹配所有路径
      packages-to-scan: com.ykx.easyexceldemo02.controller  # 扫描的包，用于自动发现api
# knife4j的增强配置，不需要增强可以不配（详细版见下小节）
knife4j:
  enable: true
  setting:
    language: zh_cn

详细全部版

# 配置knife4j，以启用swagger文档的增强功能和定制化展示
knife4j:
  # 启用knife4j扩展
  enable: true
  # 配置展示的文档分组
  documents:
    - 
      # 文档分组标题
      group: 2.x版本
      # 文档分组描述
      name: 接口签名
      # 指定接口文档的位置
      locations: classpath:sign/*
  # 配置knife4j的展示细节和功能开关
  setting:
    # 设置界面语言
    language: zh-cn
    # 启用swagger模型展示
    enable-swagger-models: true
    # 启用文档管理功能
    enable-document-manage: true
    # 设置swagger模型的显示名称
    swagger-model-name: 实体类列表
    # 是否显示版本信息
    enable-version: false
    # 是否启用参数缓存刷新
    enable-reload-cache-parameter: false
    # 启用后端脚本支持
    enable-after-script: true
    # 过滤特定方法类型的multipart/form-data接口
    enable-filter-multipart-api-method-type: post
    # 是否过滤所有multipart/form-data类型的接口
    enable-filter-multipart-apis: false
    # 启用请求缓存
    enable-request-cache: true
    # 是否显示自定义主机名
    enable-host: false
    # 设置自定义的主机名
    enable-host-text: 192.168.0.193:8000
    # 启用自定义首页
    enable-home-custom: true
    # 设置自定义首页的路径
    home-custom-path: classpath:markdown/home.md
    # 是否启用搜索功能
    enable-search: false
    # 是否显示页脚
    enable-footer: false
    # 启用自定义页脚内容
    enable-footer-custom: true
    # 设置自定义页脚的内容
    footer-custom-content: apache license 2.0 | copyright 2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)
    # 是否启用动态参数
    enable-dynamic-parameter: false
    # 启用调试模式
    enable-debug: true
    # 启用openapi 3.0的支持
    enable-open-api: false
    # 启用接口分组功能
    enable-group: true
  # 是否启用cors跨域支持
  cors: false
  # 是否启用生产模式
  production: false
  # 配置基本的认证信息
  basic:
    # 启用基本认证
    enable: false
    # 设置用户名
    username: test
    # 设置密码
    password: 12313

注意：要使用knife4j提供的增强，knife4j.enable=true必须开启

各个配置属性说明如下：

属性

默认值

说明值

knife4j.enable

false

是否开启knife4j增强模式

knife4j.cors

false

是否开启一个默认的跨域配置,该功能配合自定义host使用

knife4j.production

false

是否开启生产环境保护策略,详情参考文档

knife4j.basic

对knife4j提供的资源提供basichttp校验,保护文档

knife4j.basic.enable

false

关闭basichttp功能

knife4j.basic.username

basic用户名

knife4j.basic.password

basic密码

knife4j.documents

自定义文档集合，该属性是数组

knife4j.documents.group

所属分组

knife4j.documents.name

类似于接口中的tag,对于自定义文档的分组

knife4j.documents.locations

markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)

knife4j.setting

前端ui的个性化配置属性

knife4j.setting.enable-after-script

true

调试tab是否显示afterscript功能,默认开启

knife4j.setting.language

zh-cn

ui默认显示语言,目前主要有两种:中文(zh-cn)、英文(en-us)

knife4j.setting.enable-swagger-models

true

是否显示界面中swaggermodel功能

knife4j.setting.swagger-model-name

swagger models

重命名swaggermodel名称,默认

knife4j.setting.enable-document-manage

true

是否显示界面中"文档管理"功能

knife4j.setting.enable-reload-cache-parameter

false

是否在每个debug调试栏后显示刷新变量按钮,默认不显示

knife4j.setting.enable-version

false

是否开启界面中对某接口的版本控制,如果开启，后端变化后ui界面会存在小蓝点

knife4j.setting.enable-request-cache

true

是否开启请求参数缓存

knife4j.setting.enable-filter-multipart-apis

false

针对requestmapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个post类型的接口地址

knife4j.setting.enable-filter-multipart-api-method-type

post

具体接口的过滤类型

knife4j.setting.enable-host

false

是否启用host

knife4j.setting.enable-host-text

false

host地址

knife4j.setting.enable-home-custom

false

是否开启自定义主页内容

knife4j.setting.home-custom-path

主页内容markdown文件路径

knife4j.setting.enable-search

false

是否禁用ui界面中的搜索框

knife4j.setting.enable-footer

true

是否显示footer

knife4j.setting.enable-footer-custom

false

是否开启自定义footer

knife4j.setting.footer-custom-content

false

自定义footer内容

knife4j.setting.enable-dynamic-parameter

false

是否开启动态参数调试功能

knife4j.setting.enable-debug

true

启用调试

knife4j.setting.enable-open-api

true

显示openapi规范

knife4j.setting.enable-group

true

显示服务分组

3. 常用注解

1. 类级别注解

`@operation`

用于描述控制器类中的单个操作。

@operation(summary = "获取用户列表", description = "返回所有用户的列表")
@getmapping("/users")
public list<user> getusers() {
    // ...
}

属性：

summary：简短描述。
description：详细说明。
tags：标签，用于分类api。
responses：响应描述。

`@tag`

用于为api操作分组。

@tag(name = "用户管理", description = "用户相关操作")
@restcontroller
@requestmapping("/users")
public class usercontroller {
    // ...
}

属性：

name：标签名。
description：标签描述。

2. 方法级别注解

`@operation`

用于描述单个操作，类似于类级别使用方式。

@operation(summary = "获取用户列表", description = "返回所有用户的列表")
@getmapping("/users")
public list<user> getusers() {
    // ...
}

属性：

summary：简短描述。
description：详细说明。
tags：标签，用于分类api。
responses：响应描述。

`@apiresponses`

用于描述api操作的响应。

@operation(summary = "获取用户列表")
@apiresponses(value = {
    @apiresponse(responsecode = "200", description = "成功", content = @content(mediatype = "application/json", schema = @schema(implementation = user.class))),
    @apiresponse(responsecode = "400", description = "请求参数错误"),
    @apiresponse(responsecode = "404", description = "找不到资源"),
    @apiresponse(responsecode = "500", description = "服务器内部错误")
})
@getmapping("/users")
public list<user> getusers() {
    // ...
}

属性：

value：包含多个@apiresponse注解。

`@apiresponse`

用于描述单个响应。

属性：

responsecode：http状态码。
description：描述信息。
content：响应内容类型和模式。

3. 参数级别注解

`@parameter`

用于描述单个参数。

@operation(summary = "获取用户详情")
@getmapping("/{id}")
public user getuser(@parameter(description = "用户id", required = true) @pathvariable long id) {
    // ...
}

属性：

name：参数名。
description：参数描述。
required：是否必须参数。
schema：参数模式。

`@parameters`

用于描述多个参数。

@operation(summary = "分页获取用户列表")
@parameters({
    @parameter(name = "page", description = "页码", required = true, schema = @schema(type = "integer", example = "1")),
    @parameter(name = "size", description = "每页数量", required = true, schema = @schema(type = "integer", example = "10"))
})
@getmapping("/users")
public list<user> getusersbypage(@requestparam int page, @requestparam int size) {
    // ...
}

属性：

value：包含多个@parameter注解。

4. 模型类注解

`@schema`

用于描述模型类和字段的信息。

@schema(description = "用户实体")
public class user {
    @schema(description = "用户id", example = "1")
    private long id;
    @schema(description = "用户名", example = "alice")
    private string name;
    @schema(description = "用户年龄", example = "30")
    private integer age;
    // getters and setters
}

属性：

description：字段描述。
example：示例值。
required：是否必须字段。
type：字段类型。

`@arrayschema`

用于描述数组类型的字段。

@schema(description = "用户列表")
public class userlistresponse {
    @arrayschema(schema = @schema(implementation = user.class), description = "用户数组")
    private list<user> users;
    // getters and setters
}

属性：

schema：数组元素的模式。
description：数组描述。

5. 文件上传相关注解

@operation(summary = "上传文件")
@postmapping(value = "/upload", consumes = mediatype.multipart_form_data_value)
public string uploadfile(@parameter(description = "文件", required = true) @requestparam("file") multipartfile file) {
    // ...
}