Spring Boot REST文档推荐Swagger3（新项目首选），零注解自动扫描、配置最轻；Swagger2兼容老项目但需显式配置；Smart-doc基于标准注释不侵入代码；REST Docs通过测试用例生成确保文档与代码一致。
Spring Boot 中为 REST 接口生成文档，核心思路是**让文档自动从代码中提取信息，而不是手写维护**。主流方案有 Swagger（含 2 和 3）、Spring REST Docs、Smart-doc、apiggs 等，各自适用不同场景。选对工具，5 分钟就能跑出可交互的文档页面。
Swagger3（推荐新项目首选）
基于 OpenAPI 3 规范，零注解也能扫描接口，配置最轻、UI 最现代。
- 在 pom.xml 中添加依赖（仅需一个）：
<dependency><br> <groupId>org.springdoc</groupId><br> <artifactId>springdoc-openapi-ui</artifactId><br> <version>1.7.0</version><br> </dependency>
- 启动应用后，直接访问 http://localhost:8080/swagger-ui.html（或新版路径
/swagger-ui/index.html）即可看到自动生成的文档 - 如需定制标题、描述、分组等，加一个
@Configuration类配置OpenAPIBean 即可，无需复杂注解
Swagger2（兼容老项目）
仍广泛使用，但需显式启用并注意版本兼容性（如 Spring Boot 2.6+ 需配合 springfox-boot-starter 或降级配置）。
- 引入两个依赖：
springfox-swagger2+springfox-swagger-ui - 新建配置类，用
@EnableSwagger2+@Configuration，通过Docket指定扫描包（如com.xxx.controller） - 接口方法上可加
@ApiOperation、参数加@ApiParam提升文档可读性，非必需但建议关键接口补充
Smart-doc（适合注重代码纯净的团队）
完全基于 Java 标准注释（如 /** */），不侵入业务代码，支持导出 HTML / Markdown / Word / Postman / JMeter 脚本。
- 无需在 Controller 中加任何 Swagger 注解，靠解析源码和注释生成文档
- Maven 插件方式集成，执行
mvn smart-doc:html即可生成静态文档 - 特别适合需要交付离线文档、审计材料或对接测试团队的场景
Spring REST Docs（强调契约与测试驱动）
文档由真实 HTTP 测试用例生成，保证“文档即测试，测试即文档”，适合高可靠性要求项目。
- 需配合 MockMvc 编写单元测试，在测试中调用接口并记录请求/响应
- 生成 AsciiDoc 或 Markdown，再转成 HTML；文档内容严格对应实际运行行为
- 学习成本略高，但能从根本上杜绝“文档与代码不一致”问题
