AI API 文档：让接口说明与代码保持一致

## 适用场景

适合内部服务、开放平台和前后端协作。文档应从真实 schema 和测试样例生成，并在发布流程中校验。

## 三步工作法

### 步骤 1：提取真实契约

使用路由、类型、验证规则和状态码作为来源，不凭记忆编写。

### 步骤 2：补充使用语境

说明认证、幂等、分页、限流、错误处理和完整调用示例。

### 步骤 3：建立同步机制

将文档校验加入 CI，接口变更时同时更新示例与版本记录。

## 可直接复制的 Prompt

> 根据接口代码和类型定义生成 API 文档。包含用途、认证、请求字段、响应、状态码、幂等与限流、成功和失败示例、常见误用。任何无法从代码确认的信息标记【待确认】。

## 进阶技巧

- 示例使用脱敏数据

- 错误码给出客户端处理建议

- 废弃字段写明迁移时间

## 交付前检查

- 字段是否与代码一致

- 示例能否实际运行

- 版本与废弃策略是否清楚

## 预期效果

减少前后端反复确认，并降低接口升级时因文档过期导致的集成故障。

## 使用边界

AI 负责整理、扩展和检查，人仍然负责事实准确性、业务判断、隐私保护与最终发布。涉及个人信息、商业机密、财务、法律或安全内容时，只能使用组织批准的工具和脱敏材料。