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 配置类）
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));
}</user>
常见问题与建议
遇到文档不显示、字段缺失、中文乱码等问题，可检查以下几点：
- 确保 Controller 类上有
@Tag(name = "用户管理", description = "用户相关接口")，否则 Knife4j 分组可能为空 - 实体类字段若用了 Lombok 的
@Data，需额外加@Schema注解，因为 Lombok 生成的 getter/setter 不含 JavaDoc，OpenAPI 无法自动提取描述 - 若使用了统一响应包装（如
Result<t></t>），需配置全局响应包装：在配置类中添加@Bean返回OpenAPI对象，并调用.components().schemas()手动定义Result结构 - 生产环境建议关闭 Swagger（通过 profile 控制）：
springdoc.api-docs.enabled=${SWAGGER_ENABLED:true}，部署时设为 false
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
