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 等生成参数约束

二、核心区别对比表

维度	Javadoc	老 Swagger (Springfox)	SpringDoc OpenAPI3
本质	Java 原生代码注释工具	OpenAPI2 规范实现	OpenAPI3 规范实现
文档对象	Java 代码、方法逻辑	HTTP 接口 API 文档	HTTP 接口 API 文档
在线调试	❌ 不支持	✅ 支持	✅ 支持
读取 Javadoc	自身就是注释源	❌ 默认不读取，需复杂配置	✅ 自动读取，无缝复用
SpringBoot3 兼容	完全兼容	❌ 废弃、不支持 jakarta	✅ 完美支持
代码侵入性	低（原生注释）	高，需大量@Api注解	极低，可只写 Javadoc
维护状态	JDK 自带永久维护	2020 年停止更新	持续活跃更新
规范标准	无 API 规范	OpenAPI 2.0	OpenAPI 3.0/3.1
产出物	离线 HTML 代码文档	在线 swagger-ui 页面	在线 swagger-ui + redoc 页面
校验注解识别	不识别	少量支持	自动识别 JSR303 校验

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

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	原生注释，无第三方注解	静态 HTML，不能调接口	后端内部阅读代码、离线代码文档
SpringFox Swagger2	大量 @Api/@ApiModelProperty 重复注解	在线调试，不读 Javadoc，过时	老旧 SpringBoot2 遗留项目
SpringDoc OpenAPI3	仅写 Javadoc，零侵入	在线调试、自动解析注释、支持新版框架	新项目、前后端对接、微服务标准

九、企业标准开发搭配

Javadoc + SpringDoc

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