SpringBoot3.0+项目使用Knife4j集成Swagger接口文档教程

一、项目简介本教程将指导你在 Spring Boot 3.0 项目中集成 SpringDoc OpenAPI 3 和 Knife4j生成美观的 API 接口文档。Knife4j官方教程二、环境要求JDK 17Spring Boot 3.0Maven 3.6三、详细步骤1. 添加依赖在pom.xml中添加以下依赖!-- SpringDoc OpenAPI 3 核心依赖 -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.8.16/version /dependency !-- Knife4j 增强UI界面 -- dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.4.0/version /dependency注意在Maven仓库查找最新版依赖2. 配置 application.yaml在配置文件中添加以下配置# 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: com.example.org.controller # knife4j的增强配置 knife4j: enable: true setting: language: zh_cn3. 访问地址ip:port写自己的项目后端接口Knife4j 文档地址:http://ip:port/doc.html原生 Swagger UI:http://ip:port/swagger-ui/index.htmlOpenAPI JSON:http://ip:port/v3/api-docsOpenAPI YAML:http://ip:port/v3/api-docs.yaml4.注解使用Knife4j 常用注解注解名称作用位置参数示例功能说明Tag​控制器类Tag(name用户, description用户管理)接口分组标签Operation​方法Operation(summary创建, description创建用户)接口基本描述Parameter​参数Parameter(nameid, descriptionID, requiredtrue)单个参数描述Parameters​方法Parameters({Parameter(...)})多个参数描述Schema​实体类/字段Schema(description用户, example张三)模型/字段描述ApiResponse​方法ApiResponse(responseCode200, description成功)单个响应描述ApiResponses​方法ApiResponses({ApiResponse(...)})多个响应描述Hidden​类/方法/字段Hidden隐藏接口/字段ExampleObject​方法参数ExampleObject(name示例, value{\name\:\test\})示例数据Content​响应Content(mediaTypeapplication/json)响应内容类型快速使用示例RestController Tag(name 用户接口) // 分组标签 class UserController { PostMapping(/user) Operation(summary 创建用户) // 接口描述 Parameters({ Parameter(name token, in ParameterIn.HEADER, required true) // 参数 }) ApiResponses({ ApiResponse(responseCode 200, description 成功) // 响应 }) public UserDTO create(RequestBody UserVO vo) { return userService.create(vo); } } Data class UserVO { Schema(description 用户名, example 张三, required true) // 字段 private String name; Hidden // 隐藏字段 private String password; }