swagger、springdoc、javadoc作用和区别

一、各自核心作用

1. Javadoc

Java 原生源码注释工具，无依赖框架

1. 作用：写在 Java 类 / 接口 / 方法上的注释，用@param@return@throws@deprecated等标签，生成离线 HTML 代码文档，面向后端开发人员看代码逻辑。
2. 核心定位：代码内部文档，只描述 Java 方法入参、出参、业务逻辑，不生成接口调试页面，和 HTTP API 无关。
3. 产出：纯代码说明文档，不能调接口。

示例：

/** * 根据ID查询用户 * @param userId 用户唯一编号 * @return 用户实体信息 */ User getUser(Long userId);

2. Swagger (原始 swagger2，常用依赖：springfox)

老牌 API 文档生成框架

1. 作用：扫描 SpringMVC / SpringBoot 接口注解（@Api@ApiOperation@ApiModel），自动生成在线可视化 API 页面，支持在线调试接口。
2. 核心定位：HTTP 接口在线文档 + 接口调试工具，前后端对接专用。
3. 痛点：
   • 停止维护，不兼容 SpringBoot3、Jakarta 包
   • 注解多、侵入代码重
   • 不原生支持 Javadoc 自动读取，需要额外配置

3. SpringDoc OpenAPI3（主流替代 Springfox-Swagger）

新一代 OpenAPI 3.0 规范实现，替代旧 Swagger2

1. 作用：完全兼容 OpenAPI3 标准，自动扫描 Spring 接口，自动读取 Javadoc 注释生成在线 API 文档，内置 swagger-ui 页面，支持在线调试。
2. 核心定位：现代版 Swagger，解决老 Swagger 兼容性问题，极简配置。
3. 优势：
   • 兼容 SpringBoot2 / SpringBoot3（jakarta）
   • 零大量注解，直接复用 Javadoc
   • 持续更新维护
   • 自动识别校验注解@NotBlank@Size等生成参数约束

二、核心区别对比表

三、三者协作关系（实际开发标准用法）

1. Javadoc 是底层基础给方法、实体写标准注释，描述参数含义、返回值、业务说明。
2. SpringDoc 自动抓取 Javadoc无需额外写@ApiOperation，直接把注释渲染到 API 文档，减少重复工作量。
3. 旧 Swagger (Springfox) 现在已淘汰 SpringBoot3 项目必须用 SpringDoc，SpringBoot2 新项目也推荐 SpringDoc。

最简开发流程

写 Javadoc 注释 → 引入 springdoc 依赖 → 启动项目访问/swagger-ui/index.html自动生成完整带注释、可调试的接口文档。

四、简单总结

1. Javadoc：给程序员看的代码说明书，和接口调试无关；
2. Swagger(springfox)：过时老 API 文档工具，代码侵入高、不支持新版 Spring；
3. SpringDoc：现代 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.html

3. 使用场景

1. 后端开发内部阅读代码，梳理类、方法逻辑；
2. 给新人做代码阅读文档；
3. 导出离线代码说明书；
4. 配合 SpringDoc 自动提取注释生成接口文档；
5. 无前后端对接需求、不需要在线调试接口时单独使用。

优缺点

优点：JDK 原生、零依赖、无代码侵入； 缺点：和 HTTP 接口无关，不能调试接口，前端看不懂。

六、旧 Swagger（SpringFox OpenAPI2）示例

1. 依赖（SpringBoot2 旧项目）

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>

2. 代码示例（需要额外 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重复写；
• 不支持 SpringBoot3（jakarta 包直接报错），已停止维护。

4. 使用场景

1. 老 SpringBoot2 遗留项目；
2. 项目搭建于 2022 年前，未升级框架；
3. 不推荐新项目使用。

缺点

1. 代码侵入极高，一套逻辑要写两遍注释（Javadoc + Swagger 注解）；
2. 停止维护，不兼容 SpringBoot3；
3. 对 JSR303 校验注解识别差。

七、SpringDoc OpenAPI3（当前主流推荐）

1. 依赖（SpringBoot2 / SpringBoot3 通用）

<!-- SpringBoot3 jakarta 无需改包，直接使用 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.2.0</version> </dependency>

2. 代码示例（完全复用 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.html

1. UI 新版 Swagger UI，自带在线调试 Try it out；
2. 自动抓取 Javadoc 注释渲染到接口文档；
3. 自动识别@NotBlank/@Size/@Min等校验注解，展示参数约束；
4. 同时提供 redoc 简洁文档：/redoc/index.html；
5. 完美兼容 SpringBoot3 jakarta，持续更新维护。

4. 使用场景

1. 所有新项目（SpringBoot2、SpringBoot3）首选；
2. 需要前后端对接、在线调试接口；
3. 希望减少重复注释，只维护一套 Javadoc；
4. 微服务、前后端分离标准方案。

八、三者直观对比总结

九、企业标准开发搭配

Javadoc + SpringDoc

1. 只写一套 Javadoc 注释；
2. SpringDoc 自动提取生成可调试在线 API 文档；
3. 既能给后端看代码，又能给前端看接口，一套注释两用；
4. 彻底抛弃旧 SpringFox Swagger。