springboot3整合knife4j详细版，包会！（不带swagger2玩）

1. 引入依赖

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

2. 配置文件

简短必要版

# 配置springdoc-openapi，用于文档化和访问APIspringdoc:# 配置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分组，用于组织和管理APIgroup-configs:-group:'default'# API分组名称paths-to-match:'/**'# 匹配所有路径packages-to-scan: com.ykx.easyexceldemo02.controller  # 扫描的包，用于自动发现API# knife4j的增强配置，不需要增强可以不配（详细版见下小节）knife4j:enable:truesetting: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-CNUi默认显示语言,目前主要有两种:中文(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

falseHOST地址

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")publicList<User>getUsers(){// ...}

属性：

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

@Tag

用于为API操作分组。

@Tag(name ="用户管理", description ="用户相关操作")@RestController@RequestMapping("/users")publicclassUserController{// ...}

属性：

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

2. 方法级别注解

@Operation

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

@Operation(summary ="获取用户列表", description ="返回所有用户的列表")@GetMapping("/users")publicList<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")publicList<User>getUsers(){// ...}

属性：

• value：包含多个@ApiResponse注解。

@ApiResponse

用于描述单个响应。

属性：

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

3. 参数级别注解

@Parameter

用于描述单个参数。

@Operation(summary ="获取用户详情")@GetMapping("/{id}")publicUsergetUser(@Parameter(description ="用户ID", required =true)@PathVariableLong 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")publicList<User>getUsersByPage(@RequestParamint page,@RequestParamint size){// ...}

属性：

• value：包含多个@Parameter注解。

4. 模型类注解

@Schema

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

@Schema(description ="用户实体")publicclassUser{@Schema(description ="用户ID", example ="1")privateLong id;@Schema(description ="用户名", example ="Alice")privateString name;@Schema(description ="用户年龄", example ="30")privateInteger age;// getters and setters}

属性：

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

@ArraySchema

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

@Schema(description ="用户列表")publicclassUserListResponse{@ArraySchema(schema =@Schema(implementation =User.class), description ="用户数组")privateList<User> users;// getters and setters}

属性：

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

5. 文件上传相关注解

@Operation(summary ="上传文件")@PostMapping(value ="/upload", consumes =MediaType.MULTIPART_FORM_DATA_VALUE)publicStringuploadFile(@Parameter(description ="文件", required =true)@RequestParam("file")MultipartFile file){// ...}

4. 访问地址

http://localhost:8080/doc.html