SpringDoc OpenAPI + Knife4j 使用指南

jpruby

已于 2024-12-31 15:12:03 修改

阅读量1k

点赞数 22

文章标签： intellij-idea java

于 2024-12-31 15:08:57 首次发布

本文链接：https://blog.youkuaiyun.com/m0_58039950/article/details/144850721

版权

SpringDoc OpenAPI + Knife4j 使用指南

背景说明

在 Spring Boot 3.x 版本中，由于不再支持 Swagger 2，原有的 springfox-swagger2 已无法使用。为了解决接口文档管理的问题，我们需要迁移到 OpenAPI 3 规范。

本文主要解决以下问题：

Spring Boot 3.x 下的 API 文档解决方案
寻找一个适合中国开发者使用习惯的 UI 界面
保持与原有 Swagger 2 注解的平滑迁移

1. Maven 依赖配置

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

2. 配置文件设置

application.yml

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs
    enabled: true
  packages-to-scan: com.jpruby.controller
  show-actuator: true

knife4j:
  enable: true
  setting:
    language: zh_cn
    enable-swagger-models: true
    enable-document-manage: true
    swagger-model-name: 实体类列表

application-prod.yml（生产环境禁用）

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

3. 常用注解说明

控制器类注解

@Tag(name = "模块名称", description = "模块描述")

接口方法注解

// 接口描述
@Operation(summary = "接口名称", description = "接口详细描述")

// 接口响应
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功描述"),
    @ApiResponse(responseCode = "404", description = "错误描述")
})

// 参数描述
@Parameter(description = "参数描述", required = true)

实体类注解

@Schema(description = "实体描述")
public class Entity {
    @Schema(description = "属性描述")
    private String field;
}

4. 使用示例

Controller 示例

@Tag(name = "用户管理", description = "用户信息的增删改查接口")
@RestController
@RequestMapping("/user")
public class UserController {

    @Operation(summary = "获取用户信息", description = "根据用户ID获取用户详细信息")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "查询成功"),
        @ApiResponse(responseCode = "404", description = "用户不存在")
    })
    @GetMapping("/{id}")
    public Result getUser(
        @Parameter(description = "用户ID", required = true)
        @PathVariable Integer id) {
        // 实现代码
    }
}

Entity 示例

@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户ID")
    private Integer id;

    @Schema(description = "用户名")
    private String username;
}