Java项目中推荐使用springdoc-openapi与Knife4j组合生成接口文档：引入对应依赖（注意Spring Boot 3.x需jakarta版）、配置application.yml启用并扫描包、用@Operation等注解描述接口，启动后访问/swagger-ui/index.html即可查看增强版UI。
在 Java 项目中，Swagger（现为 OpenAPI）和 Knife4j 是主流的接口文档自动生成工具。Swagger 提供标准规范与基础支持，Knife4j 是其国产增强版，界面更友好、功能更丰富（如离线导出、调试、分组、个性化配置等）。核心思路是：引入依赖 → 配置扫描路径 → 用注解描述接口 → 启动服务后访问 UI 页面。
添加依赖（Spring Boot 2.x / 3.x）
根据 Spring Boot 版本选择对应依赖。Spring Boot 2.x 常用 springfox，但已停止维护；推荐直接使用官方支持的 springdoc-openapi（适配 OpenAPI 3.x），Knife4j 也基于它做前端增强。
以 Spring Boot 3.x + Maven 为例：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta</artifactId>
<version>4.4.0</version>
</dependency>
注意：Spring Boot 3.x 使用 Jakarta EE 9+（包名从 javax.* 变为 jakarta.*），必须选带 jakarta 后缀的 Knife4j 依赖，否则启动报错。
立即学习“Java免费学习笔记（深入）”；
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
基础配置（无需额外 Java 配置类）
springdoc 默认自动配置，只需在 application.yml 中简单设置即可启用：
- 开启 Swagger UI：
springdoc.api-docs.enabled=true - 启用 Knife4j 增强 UI：
springdoc.swagger-ui.enabled=true - 指定扫描包（避免扫描过多类影响性能）：
springdoc.packages-to-scan=com.example.controller - 设置文档标题/描述（可选）：
springdoc.api-docs.title=用户服务接口
启动项目后，访问 http://localhost:8080/swagger-ui.html（旧路径）或 http://localhost:8080/swagger-ui/index.html（新路径），即可看到 Knife4j 界面。
用注解描述接口（关键！）
仅引入依赖不会生成完整文档，需配合 OpenAPI 注解说明参数、返回值、异常等。常用注解如下：
-
@Operation(summary = "获取用户列表", description = "分页查询所有用户")—— 描述接口功能 -
@Parameter(name = "page", description = "页码", required = true)或直接在方法参数上加@RequestParam @Parameter(...) -
@ApiResponses({@ApiResponse(responseCode = "200", description = "成功", content = @Content(schema = @Schema(implementation = User.class)))})—— 定义响应结构 - 对请求体（
@RequestBody）实体类，用@Schema(description = "用户信息")和字段级@Schema(description = "用户名")补充说明
示例 Controller 方法片段：
@Operation(summary = "创建用户")
@ApiResponses({
@ApiResponse(responseCode = "201", description = "创建成功", content = @Content(schema = @Schema(implementation = User.class))),
@ApiResponse(responseCode = "400", description = "参数错误")
})
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody @Schema(description = "用户对象") User user) {
return ResponseEntity.status(HttpStatus.CREATED).body(userService.save(user));
}
常见问题与建议
遇到文档不显示、字段缺失、中文乱码等问题，可检查以下几点：
- 确保 Controller 类上有
@Tag(name = "用户管理", description = "用户相关接口")，否则 Knife4j 分组可能为空 - 实体类字段若用了 Lombok 的
@Data，需额外加@Schema注解，因为 Lombok 生成的 getter/setter 不含 JavaDoc，OpenAPI 无法自动提取描述 - 若使用了统一响应包装（如
Result<T>），需配置全局响应包装：在配置类中添加@Bean返回OpenAPI对象，并调用.components().schemas()手动定义Result结构 - 生产环境建议关闭 Swagger（通过 profile 控制）：
springdoc.api-docs.enabled=${SWAGGER_ENABLED:true}，部署时设为 false
