一、各自核心作用1. JavadocJava 原生源码注释工具无依赖框架作用写在 Java 类 / 接口 / 方法上的注释用paramreturnthrowsdeprecated等标签生成离线 HTML 代码文档面向后端开发人员看代码逻辑。核心定位代码内部文档只描述 Java 方法入参、出参、业务逻辑不生成接口调试页面和 HTTP API 无关。产出纯代码说明文档不能调接口。示例/** * 根据ID查询用户 * param userId 用户唯一编号 * return 用户实体信息 */ User getUser(Long userId);2. Swagger (原始 swagger2常用依赖springfox)老牌 API 文档生成框架作用扫描 SpringMVC / SpringBoot 接口注解ApiApiOperationApiModel自动生成在线可视化 API 页面支持在线调试接口。核心定位HTTP 接口在线文档 接口调试工具前后端对接专用。痛点停止维护不兼容 SpringBoot3、Jakarta 包注解多、侵入代码重不原生支持 Javadoc 自动读取需要额外配置3. SpringDoc OpenAPI3主流替代 Springfox-Swagger新一代 OpenAPI 3.0 规范实现替代旧 Swagger2作用完全兼容 OpenAPI3 标准自动扫描 Spring 接口自动读取 Javadoc 注释生成在线 API 文档内置 swagger-ui 页面支持在线调试。核心定位现代版 Swagger解决老 Swagger 兼容性问题极简配置。优势兼容 SpringBoot2 / SpringBoot3jakarta零大量注解直接复用 Javadoc持续更新维护自动识别校验注解NotBlankSize等生成参数约束二、核心区别对比表维度Javadoc老 Swagger (Springfox)SpringDoc OpenAPI3本质Java 原生代码注释工具OpenAPI2 规范实现OpenAPI3 规范实现文档对象Java 代码、方法逻辑HTTP 接口 API 文档HTTP 接口 API 文档在线调试❌ 不支持✅ 支持✅ 支持读取 Javadoc自身就是注释源❌ 默认不读取需复杂配置✅ 自动读取无缝复用SpringBoot3 兼容完全兼容❌ 废弃、不支持 jakarta✅ 完美支持代码侵入性低原生注释高需大量Api注解极低可只写 Javadoc维护状态JDK 自带永久维护2020 年停止更新持续活跃更新规范标准无 API 规范OpenAPI 2.0OpenAPI 3.0/3.1产出物离线 HTML 代码文档在线 swagger-ui 页面在线 swagger-ui redoc 页面校验注解识别不识别少量支持自动识别 JSR303 校验三、三者协作关系实际开发标准用法Javadoc 是底层基础给方法、实体写标准注释描述参数含义、返回值、业务说明。SpringDoc 自动抓取 Javadoc无需额外写ApiOperation直接把注释渲染到 API 文档减少重复工作量。旧 Swagger (Springfox) 现在已淘汰 SpringBoot3 项目必须用 SpringDocSpringBoot2 新项目也推荐 SpringDoc。最简开发流程写 Javadoc 注释 → 引入 springdoc 依赖 → 启动项目访问/swagger-ui/index.html自动生成完整带注释、可调试的接口文档。四、简单总结Javadoc给程序员看的代码说明书和接口调试无关Swagger(springfox)过时老 API 文档工具代码侵入高、不支持新版 SpringSpringDoc现代 API 文档工具兼容新版框架自动复用 Javadoc是现在项目标准选择。五、Javadoc 完整示例1. 代码示例实体 Controller 标准注释import javax.validation.constraints.NotBlank; /** * 用户实体 */ public class User { /** 用户id */ private Long id; NotBlank(message 用户名不能为空) /** 用户登录账号 */ private String username; // getter/setter }import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; /** * 用户相关接口 */ RestController RequestMapping(/user) public class UserController { /** * 根据用户id查询用户信息 * param userId 用户唯一主键 * return 返回完整用户实体 */ GetMapping(/{userId}) public User getUserInfo(PathVariable Long userId) { User user new User(); user.setId(userId); user.setUsername(test); return user; } }2. 界面生成方式mvn javadoc:javadoc/ IDEA 工具生成界面纯静态 HTML只有代码说明无接口调试按钮展示内容类说明、方法注释、param、return、字段注释访问本地打开 target/site/apidocs/index.html3. 使用场景后端开发内部阅读代码梳理类、方法逻辑给新人做代码阅读文档导出离线代码说明书配合 SpringDoc 自动提取注释生成接口文档无前后端对接需求、不需要在线调试接口时单独使用。优缺点优点JDK 原生、零依赖、无代码侵入 缺点和 HTTP 接口无关不能调试接口前端看不懂。六、旧 SwaggerSpringFox OpenAPI2示例1. 依赖SpringBoot2 旧项目dependency groupIdio.springfox/groupId artifactIdspringfox-swagger2/artifactId version2.9.2/version /dependency dependency groupIdio.springfox/groupId artifactIdspringfox-swagger-ui/artifactId version2.9.2/version /dependency2. 代码示例需要额外 Swagger 专属注解import io.swagger.annotations.Api; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import io.swagger.annotations.ApiOperation; Api(tags 用户管理模块) RestController RequestMapping(/user) public class UserController { ApiOperation(value 根据ID获取用户, notes 传入用户主键返回用户全部信息) GetMapping(/{userId}) public User getUserInfo(PathVariable Long userId) { return new User(); } } ApiModel(description 用户实体) public class User { ApiModelProperty(value 用户主键id, example 1001) private Long id; ApiModelProperty(value 用户名, required true) private String username; }3. 界面访问地址http://localhost:8080/swagger-ui.html可视化在线页面分类展示所有接口、请求参数、返回示例内置Try it out按钮可在线发起 HTTP 请求调试默认不会读取 Javadoc注释全靠Api/ApiModelProperty重复写不支持 SpringBoot3jakarta 包直接报错已停止维护。4. 使用场景老 SpringBoot2 遗留项目项目搭建于 2022 年前未升级框架不推荐新项目使用。缺点代码侵入极高一套逻辑要写两遍注释Javadoc Swagger 注解停止维护不兼容 SpringBoot3对 JSR303 校验注解识别差。七、SpringDoc OpenAPI3当前主流推荐1. 依赖SpringBoot2 / SpringBoot3 通用!-- SpringBoot3 jakarta 无需改包直接使用 -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.2.0/version /dependency2. 代码示例完全复用 Javadoc不需要额外注解控制器和实体只写 Javadoc无需任何 swagger 专属注解/** * 用户模块控制器 */ RestController RequestMapping(/user) public class UserController { /** * 根据用户ID查询用户详情 * param userId 用户主键ID * return 用户完整信息 */ GetMapping(/{userId}) public User getUserInfo(PathVariable Long userId) { return new User(); } } /** * 用户实体类 */ public class User { /** 用户主键 */ private Long id; /** 登录用户名不能为空 */ NotBlank private String username; }可选少量增强注解非必需Parameter、Schema不写也能正常生成文档。3. 界面访问地址http://localhost:8080/swagger-ui/index.htmlUI 新版 Swagger UI自带在线调试 Try it out自动抓取 Javadoc 注释渲染到接口文档自动识别NotBlank/Size/Min等校验注解展示参数约束同时提供 redoc 简洁文档/redoc/index.html完美兼容 SpringBoot3 jakarta持续更新维护。4. 使用场景所有新项目SpringBoot2、SpringBoot3首选需要前后端对接、在线调试接口希望减少重复注释只维护一套 Javadoc微服务、前后端分离标准方案。八、三者直观对比总结工具代码特征页面能力核心使用场景Javadoc原生注释无第三方注解静态 HTML不能调接口后端内部阅读代码、离线代码文档SpringFox Swagger2大量Api/ApiModelProperty重复注解在线调试不读 Javadoc过时老旧 SpringBoot2 遗留项目SpringDoc OpenAPI3仅写 Javadoc零侵入在线调试、自动解析注释、支持新版框架新项目、前后端对接、微服务标准九、企业标准开发搭配Javadoc SpringDoc只写一套 Javadoc 注释SpringDoc 自动提取生成可调试在线 API 文档既能给后端看代码又能给前端看接口一套注释两用彻底抛弃旧 SpringFox Swagger。