Java API接口如何文档化

Java API 接口的文档化是开发过程中非常重要的一环，主流做法有 Javadoc（标准做法）、OpenAPI/Swagger（Web API）、以及结合构建工具与文档平台等方式。下面按常见场景系统说明。

一、最基础：使用 Javadoc（适合所有 Java API）

1️⃣ 什么是 Javadoc

Javadoc 是 Java 官方提供的文档生成工具，通过注释自动生成 HTML API 文档。

2️⃣ 基本写法

/**
 * 用户服务接口
 */
public interface UserService {

    /**
     * 根据ID获取用户
     *
     * @param id 用户ID
     * @return 用户对象
     * @throws IllegalArgumentException 当ID非法时
     */
    User getUserById(Long id);
}

3️⃣ 常用标签

4️⃣ 生成文档

javadoc -d docs src/main/java/com/example/**/*.java

✅ 优点

• 官方标准
• IDE 自动提示
• 适合库、SDK、内部 API

❌ 不足

• 不适合 REST API
• 不适合前后端对接

二、REST API：使用 OpenAPI / Swagger（最常见）

1️⃣ 核心思想

通过注解描述接口 → 自动生成在线文档

2️⃣ 常用工具

• Swagger 2
• Springfox（旧）
• ✅ Springdoc OpenAPI（推荐）

3️⃣ Spring Boot 示例（springdoc）

依赖

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

Controller 示例

@RestController
@RequestMapping("/users")
@Tag(name = "用户接口", description = "用户相关操作")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户")
    public UserDTO getUser(
        @Parameter(description = "用户ID") @PathVariable Long id
    ) {
        return userService.getUser(id);
    }
}

访问文档

• Swagger UI：

  http://localhost:8080/swagger-ui.html
  

• OpenAPI JSON：

  http://localhost:8080/v3/api-docs
  

✅ 优点

• 自动生成
• 可在线调试
• 前后端协作友好

三、DTO / 模型文档化

@Schema(description = "用户数据传输对象")
public class UserDTO {

    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", example = "zhangsan")
    private String username;
}

四、进阶：结合构建与发布

1️⃣ 发布 Javadoc

• GitHub Pages
• GitLab Pages
• Maven 站点

mvn javadoc:javadoc

2️⃣ 导出 OpenAPI

mvn generate-resources

或：

curl http://localhost:8080/v3/api-docs > openapi.json

五、内部 API 文档规范建议

✅ 统一风格

• 每个接口必须有说明
• 错误码集中管理
• 示例完整

✅ 文档内容建议包含

• 接口地址
• 请求方式
• 参数说明
• 返回结构
• 错误情况
• 示例请求/响应

六、不同场景如何选择？

七、总结一句话

Java API 文档化的核心是：用注释描述意图，用工具生成标准格式，用文档降低沟通成本。

如果你愿意，我可以：

• ✅ 给你一个 完整 Spring Boot + OpenAPI 示例
• ✅ 帮你制定 团队 API 文档规范
• ✅ 帮你把现有代码补充成规范文档

你可以直接告诉我你的使用场景。