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 类配置 OpenAPI Bean 即可，无需复杂注解

Swagger2（兼容老项目）

仍广泛使用，但需显式启用并注意版本兼容性（如 Spring Boot 2.6+ 需配合 springfox-boot-starter 或降级配置）。

Java调试

通过 JDWP 实现 Java 远程调试：连接远程 JVM、设置断点、单步执行代码、查看变量值、获取调用栈。适用于需要调试远程 Java 应用、排查运行时状态、追踪代码执行流程的场景。 术语注解 JDWP：Java Debug Wire Protocol，Java 调试有线协议（Java 远程调试底层通信协议） remote JVM：远程 Java 虚拟机 step through code：代码单步调试（步入 / 步过 / 步出调试） inspect variables：变量查看 / 变量检视 stac

下载

• 引入两个依赖：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；文档内容严格对应实际运行行为
• 学习成本略高，但能从根本上杜绝“文档与代码不一致”问题