如何文档化java API接口

文档化 Java API 接口常见做法可以分为代码级文档、自动生成文档和接口管理平台三类。下面按实用程度给你一个清晰指南。

一、代码级文档（最基础）

1. Javadoc（Java 官方标准）

在类、方法、参数上写注释，使用 Javadoc 标签。

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

    /**
     * 根据ID获取用户信息
     *
     * @param id 用户ID
     * @return 用户对象
     * @throws UserNotFoundException 用户不存在
     */
    User getUserById(Long id);
}

生成 HTML 文档：

javadoc -d docs *.java

✅ 优点：标准、IDE 友好
❌ 缺点：不适合前后端联调

二、自动生成 API 文档（最推荐）

2. Swagger / OpenAPI（最流行）

适合 RESTful API。

Spring Boot + Swagger 示例

依赖（Springdoc）：

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

代码示例：

@RestController
@RequestMapping("/users")
public class UserController {

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

访问文档：

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

✅ 优点：可视化、可测试
✅ 支持 OpenAPI 标准

3. Spring RestDocs（更严谨）

基于测试生成文档，适合对文档准确性要求高的团队。

mockMvc.perform(get("/users/1"))
       .andDo(document("user-get"));

✅ 文档与测试绑定
❌ 上手成本略高

三、接口管理平台（团队协作）

4. 常见平台

• YApi
• Apifox
• Postman
• ShowDoc

适合：

• 前后端分离
• 多团队协作
• 接口版本管理

四、推荐组合（实战）

五、文档规范建议

• 写明：功能、参数、返回值、错误码
• 示例请求 / 响应
• 接口版本（v1 / v2）
• 权限说明

如果你用的是 Spring Boot / 普通 Java / 内部 SDK，可以告诉我，我可以给你更具体的模板。