java API接口怎样文档化

在 Java 项目中，API 接口文档化通常有几种常见方式，从“最基础”到“最自动化”依次如下：

一、使用 Javadoc（最基础）

适合：代码级 API（类、方法）文档

1. 写规范的注释

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

    /**
     * 根据ID获取用户
     *
     * @param id 用户ID
     * @return 用户对象
     */
    User getUserById(Long id);
}

2. 生成文档

javadoc -d docs User.java

或 Maven：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
</plugin>

✅ 优点：零依赖
❌ 缺点：不适合 REST API

二、REST API 文档（最常用方案）

✅ 方案 1：Swagger / OpenAPI（强烈推荐）

适合：Spring Boot REST API

1. 引入依赖

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

2. 接口注解

@Operation(summary = "获取用户")
@GetMapping("/users/{id}")
public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
    return userService.get(id);
}

3. 访问文档

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

✅ 自动生成
✅ 可调试
✅ 支持 JSON / YAML

✅ 方案 2：Springfox Swagger（老项目）

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
</dependency>

⚠️ 已不再维护，不推荐新项目使用

三、使用注解 + 文档生成工具

✅ Spring Rest Docs（高质量文档）

适合：需要“示例 + 测试驱动”的文档

@Test
public void getUser() {
    mockMvc.perform(get("/users/1"))
           .andDo(document("user-get"));
}

生成 AsciiDoc / HTML

✅ 文档与测试一致
❌ 配置稍复杂

四、手动文档（API 平台）

常见工具：

• Postman
• Apifox
• YApi
• RAP2

✅ 非技术人员可维护
✅ 支持 Mock
❌ 与代码不同步

五、推荐组合（2024 最佳实践）

六、示例：标准 REST API 文档结构

/users:
  get:
    summary: 获取用户列表
    parameters:
      - name: page
        in: query
        type: integer

如果你愿意，可以告诉我：

• 是否是 Spring Boot
• 是 对内 / 对外 API
• 是否需要 自动生成 + 调试

我可以直接给你一套可落地的方案或模板。