推荐新项目使用knife4j集成swagger 3，需引入springdoc-openapi与knife4j依赖，启动后访问/doc.html；接口需添加@operation等openapi注解；生产环境须禁用文档页面。
Java 项目中用 Swagger 或 Knife4j 生成接口文档，核心是引入依赖、配置扫描、启动服务后访问对应 UI 页面。Knife4j 是 Swagger 的增强版，界面更友好、功能更丰富（如离线文档导出、调试增强），推荐新项目直接用 Knife4j。
1. Spring Boot 项目集成 Knife4j（推荐）
Knife4j 基于 Swagger 3（即 springdoc-openapi），适用于 Spring Boot 2.6+ 和 Spring Boot 3.x。
- 添加 Maven 依赖（以 Spring Boot 3.x 为例）：
- 无需额外 Java 配置类，自动生效；如需自定义（如分组、标题），可加
@Bean配置OpenAPI对象 - 启动项目后，访问 http://localhost:8080/doc.html 即可打开 Knife4j UI（注意不是
/swagger-ui.html） - 接口会自动识别
@RestController+@Operation（来自io.swagger.v3.oas.annotations）等注解
2. 给接口添加说明注解（让文档更清晰）
光有依赖只能看到基础路径和参数，要写出可读性强的文档，需在 Controller 方法上补充 OpenAPI 标准注解：
@Operation(summary = "用户登录", description = "根据手机号和密码获取 token")-
@Parameter(name = "loginDTO", description = "登录请求体", required = true)（用于 @RequestBody） @ApiResponse(responseCode = "200", description = "登录成功", content = @Content(schema = @Schema(implementation = Result.class)))- 实体类字段可用
@Schema(description = "用户昵称")注解增强说明
3. Swagger 2（旧版，仅兼容老项目）
若项目仍在用 Spring Boot 2.1–2.5 且基于 springfox-swagger2，则走传统 Swagger 2 路线：
- 引入
springfox-swagger2和springfox-swagger-ui（注意版本对齐，如 2.9.2） - 写一个
@Configuration类，用Docket配置 API 扫描包、分组、基本信息 - 访问 http://localhost:8080/swagger-ui.html
- ⚠️ 注意：Swagger 2 不支持 Spring Boot 2.6+（因 Spring 默认禁用 Spring MVC path matching 的 ant-style），强行使用需降级或改配置，不建议新项目采用
4. 生产环境注意事项
文档页面不能暴露在生产环境，需按环境控制开关：
- Knife4j：在
application-prod.yml中关闭
enable: false
- Swagger 3（springdoc）：通过
springdoc.api-docs.enabled=false和springdoc.swagger-ui.enabled=false双重关闭 - 还可结合 Profile，在非 dev/test 环境跳过 Knife4j 的 starter 自动配置
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
