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

是清醒也是知趣

于 2024-07-21 21:23:44 发布

阅读量1.1k

点赞数 25

分类专栏： Java高级文章标签： java intellij-idea

本文链接：https://blog.csdn.net/qq_51774011/article/details/140594038

版权

Java高级专栏收录该内容

8 篇文章 0 订阅

订阅专栏

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) {
    // ...
}

4. 访问地址

http://localhost:8080/doc.html
在这里插入图片描述

是清醒也是知趣

关注

25
点赞
踩
28

收藏

觉得还不错? 一键收藏
0
评论
springboot3整合knife4j详细版，包会！（不带swagger2玩）

springboot3在整合swagger2或者3时均不太好使，而且swagger的默认ui页面真的一言难尽，官方现在推荐使用springdoc-openapi集成接口文档，但是经过测试一些注解个性化文档时存在不好使的情况，而且ui界面依然感觉不好看。本文详细记录了knife4j集成接口文档的详细使用步骤，配置详解以及注解详解。绝对是up亲身测验过的，绝对好用！！！百度了很多内容，踩了很多坑后的整理版。
复制链接

扫一扫