先给结论：AI生成接口文档，最可靠的顺序是“先盘点真实接口，再整理字段和规则，最后生成阅读友好的文档”。墨刀AI客户端可以在本地项目中分析路由、控制器、Schema、鉴权、错误处理、测试样例和变更记录，帮助生成 API 文档初稿；接口是否准确，仍要以实际代码、测试响应和研发确认结果为准。
一份可联调的接口文档，不能只写 URL 和参数类型，还要说明谁能调用、什么时候能调用、成功后改变什么、失败如何处理、重复请求是否安全。本文把“AI生成接口文档”拆成从代码证据到联调交付的完整方法。
为什么接口文档要以代码和测试为证据
手写文档最常见的失真有三种：文档写了新字段但代码没有；代码改变了错误码但文档没更新；示例能成功，却没有说明鉴权、幂等、分页和失败恢复。AI如果只读一份旧文档，会把这些错误放大成一份看似完整的说明。
因此，墨刀AI客户端处理接口文档时，应优先读取当前分支的路由注册、控制器或处理函数、请求/响应模型、校验规则、错误定义、测试脚本和最近变更，再把人工文档作为背景或补充。没有证据的字段要标记为“待确认”，不要为了填满表格而猜测。
准备本地项目：给AI一张接口证据地图
建议先建立一个接口文档任务目录，或者在已有项目中明确以下入口：
| 证据位置 | 重点读取内容 | 文档产物 |
|---|---|---|
| 路由/控制器 | HTTP方法、路径、处理入口、版本前缀 | 接口清单、调用顺序和权限入口 |
| Schema/DTO/类型 | 字段类型、必填、枚举、默认值和嵌套结构 | 请求与响应字段表 |
| 校验/错误定义 | 错误码、错误消息、状态码、业务失败条件 | 错误处理和排查说明 |
| 认证中间件 | 登录方式、角色、权限、令牌和租户范围 | 鉴权、权限和安全注意事项 |
| 测试与样例 | 真实请求、响应、边界数据和失败场景 | 可复制的联调示例与验证依据 |
| 变更记录 | 新增、删除、废弃、兼容和迁移说明 | 版本差异和升级提醒 |
如果项目使用多个服务，先让AI输出服务、路由和版本的清单，再选择一个业务域深入；不要在第一轮把所有微服务混成一张巨大表格。关于本地文件边界，可参考墨刀AI本地项目怎么用。
第一步：生成接口清单，而不是直接写长文
接口文档的第一产物应该是一张可核对的清单，至少包括：接口ID、方法、路径、版本、模块、鉴权、稳定性、状态和证据文件。让研发先确认“有没有漏接口、有没有把内部接口当公开接口”，再生成详细章节。
| 接口ID | 方法与路径 | 用途 | 鉴权/状态 | 证据 |
|---|---|---|---|---|
| MEMBER-001 | POST /v1/members/import | 批量导入成员 | 管理员；草稿 | 路由、控制器、接口测试 |
| MEMBER-002 | GET /v1/members | 分页查询成员 | 团队成员；稳定 | 路由、Schema、前端调用 |
| MEMBER-003 | DELETE /v1/members/{id} | 移除成员 | 管理员；需审计 | 控制器、权限测试、审计日志 |
清单中的“状态”很重要。把内部调试接口、已废弃接口、实验版本和公开联调接口区分开，能避免其他团队误用。若状态无法从代码和变更中确认，输出“需要负责人确认”，不要自行判断。
第二步：生成字段表，把规则写在字段旁边
字段表不应只列名称和类型。联调最需要的是必填、来源、格式、枚举、默认值、脱敏、空值和错误条件：
| 字段 | 类型/必填 | 规则 | 错误或注意事项 |
|---|---|---|---|
| team_id | string / 是 | 当前用户所属团队，不能跨租户 | 不存在或无权限时拒绝 |
| role | enum / 是 | 只接受项目定义的角色值 | 未知值不应静默降级 |
| members | array / 是 | 数量上限、邮箱格式、重复项规则 | 部分失败是否允许，需以实现确认 |
| request_id | string / 否 | 用于幂等或链路追踪 | 重复请求的处理方式要写清 |
对于嵌套数组、金额、时间、时区、文件和富文本，要求AI提供最小有效值、最大边界值和非法示例。不要让“可选”掩盖“空字符串是否等同于未传”的差异。
第三步：补齐鉴权、错误、幂等和分页
一份接口文档是否能减少联调来回，往往取决于这些非成功路径：
- 鉴权：需要什么令牌、角色、团队或项目权限，权限不足返回什么。
- 错误：状态码、业务错误码、可展示消息、重试建议和排查字段。
- 幂等：重复提交如何判定，网络重试会不会创建多份数据。
- 分页：页码还是游标、默认和最大条数、排序稳定性和总数语义。
- 限流：频率限制、响应头、退避方式和恢复时间。
- 版本：兼容策略、废弃时间、字段新增和删除规则。
让AI从错误定义和测试脚本中找证据，找不到时列成待确认项。不要依据常见框架习惯自动编造错误码或重试规则。
AI生成API文档提示词模板
| 部分 | 可复用写法 |
|---|---|
| 范围 | 只分析【服务/目录/分支】中的公开业务接口，不包含内部调试路由和已废弃版本。 |
| 证据优先级 | 以当前路由、处理函数、Schema、错误定义和接口测试为准；人工文档用于补充，冲突必须列出。 |
| 输出结构 | 先给接口清单，再按接口输出用途、权限、请求、响应、错误、幂等、分页、示例、版本和变更说明。 |
| 示例规则 | 只使用项目中的脱敏测试数据，给出一个最小成功示例和至少一个失败示例。 |
| 格式 | 输出为可评审 Markdown；如果建议 OpenAPI 结构，先说明字段来源与无法确认的部分。 |
| 限制 | 不修改源码，不执行生产请求，不虚构未找到的字段、状态码或鉴权规则。 |
如果当前产品或导出链路没有确认支持某种标准文件，不要把“OpenAPI-compatible draft”写成已经自动导出 OpenAPI。先生成可评审的 Markdown 或结构化草稿，再由研发决定是否转成标准文件。
接口变更时，让AI生成差异说明
接口文档最容易在发布后失效。每次变更可以让客户端比较基线和当前分支，输出：
- 新增：新接口、新字段、新枚举和新错误。
- 修改：类型、必填、默认值、权限、状态码和业务语义变化。
- 废弃：旧接口或字段的替代方式、迁移时间和兼容窗口。
- 风险：可能影响的调用方、前端页面、脚本和测试。
- 验证：需要更新的契约测试、集成测试、示例和监控。
把差异说明与代码提交或版本号关联，联调人员就能快速知道自己需要更新什么。若项目使用Git，可以先查看AI生成的差异，再将确认后的文档放进评审目录，不要直接覆盖历史版本。
联调前的接口文档验收清单
| 检查项 | 通过标准 |
|---|---|
| 路径和方法 | 能在当前代码和路由注册中找到，版本前缀一致 |
| 鉴权与权限 | 成功、未登录、无权限和跨团队场景均有说明 |
| 字段规则 | 必填、类型、枚举、空值、长度、默认值和脱敏明确 |
| 错误处理 | 常见状态码、业务码、消息和重试边界可观察 |
| 数据语义 | 时间、金额、时区、分页、排序和一致性说明清楚 |
| 示例可复现 | 使用脱敏测试数据，响应与实际测试或运行结果一致 |
| 版本与差异 | 新增、修改、废弃和兼容窗口有负责人确认 |
验收时最好用一个真实的联调请求逐项走过文档。如果字段表写得很完整，但示例无法运行，仍然不能算交付完成。
把API文档交给产品、前端和测试
产品关心能力边界和业务状态，前端关心字段、错误和示例，测试关心可验证条件，运维关心版本、限流、日志和告警。交接时建议附上接口清单、变更差异、待确认问题、测试证据和负责人，而不是只发一个没有版本号的链接。
需要团队共同评论、管理版本或把接口说明和原型放在一起时，可以把确认后的材料带入墨刀工作台与企业空间；客户端安装与能力边界见墨刀AI客户端使用指南。
AI生成接口文档的七个常见错误
- 只读旧文档，不看当前路由和测试。
- 把内部调试接口混入公开接口清单。
- 只写成功响应，没有错误、权限和重试。
- 把可选字段、空值和默认值混为一谈。
- 示例使用真实密钥、客户数据或不可复现的环境。
- 新增字段写进文档，却没有说明兼容和版本。
- 生成后直接覆盖旧文档，丢失变更和回滚依据。
常见问题
墨刀AI客户端能自动从代码发布API文档吗？
本文只把它定位为本地项目分析和文档初稿工具。是否能导出、发布某种标准格式，取决于当前客户端、项目脚本和团队流程；发布前必须由研发核对并完成联调。
接口文档必须使用OpenAPI吗？
不一定。Markdown 适合评审和快速交接，OpenAPI 适合工具链消费。先保证内容以真实代码和测试为证据，再根据团队需要选择格式，不要为了格式而补写不存在的规则。
代码和文档冲突时以谁为准？
先暂停自动生成，列出冲突位置、版本和影响，交给接口负责人确认。代码也可能处于未发布分支，不能脱离版本语境简单地说“代码永远正确”。
如何防止接口文档越写越长？
先用接口清单筛选公开和当前版本，再按调用方需要组织章节。把内部实现细节、历史变更和联调示例分层展示，首屏先给能完成调用所需的信息。
AI生成接口文档的核心，是把真实代码、测试和版本变化翻译成团队可以共同遵守的契约。用墨刀AI客户端先盘点证据，再生成字段、错误、示例和差异，最后用一次真实联调验证，文档才会真正减少沟通成本。需要开始本地项目任务时，可先下载墨刀AI客户端。
