
接口规范变成 Markdown 后,还需要交接原件
你拿到一份 OpenAPI 或 Swagger 规范,想让 AI 帮忙写客户端。直接塞进对话不便阅读,于是先把规范转成 Markdown。转换结果更容易浏览,但接下来真正要确认的是:AI 将按哪一个版本、哪一组接口、哪一种请求与响应来实现?
AIGoCode 工具目录列有 OpenAPI 转 Markdown,说明用途是把 OpenAPI / Swagger 规范整理成 Markdown 接口文档。本文以这个转换入口为起点,给出一份接口交接检查清单。下文不假定转换器会完整展开每一种引用或复杂约束;具体支持范围请查当前工具说明,并以原规范逐项核对。
先把“方便阅读”与“实现依据”分别标清
建议保存三份材料:原始规范、未经手改的转换结果、经过人工核对的交接说明。原始规范负责保留完整定义,转换结果方便阅读,交接说明标出本次实现范围与待确认问题。这是推荐的文件组织方式,不代表工具自带版本管理。
记录来源、取得时间、文档版本,以及本次准备使用的环境。不要只用文件名中的“最新”判断版本。若规范中的服务器地址与团队确认的测试环境不同,先由接口负责人说明差异,不让 AI 自行猜测哪个地址可用。
“成功生成 Markdown”只说明你完成了一次格式整理。它不能单独证明规范有效、服务在线,或生成的客户端已经通过接口测试。把这些验收项分开,才不会用一个结果替代三个结论。
从一个接口开始,建立逐项对应表
先选一个范围清楚的接口,按“方法 + 路径”定位,而不是只搜索摘要名称。下面以虚构的订单查询任务说明核对方式,不是 AIGoCode 的接口说明,也不是可以直接调用的地址。
| 核对项 | 原规范需要找什么 | 交接说明应留下什么 |
|---|---|---|
| 方法与路径 | 目标操作及路径参数 | 本次实现哪个操作,哪些不在范围内 |
| 请求参数 | 参数所在位置、必填规则和类型 | 参数从哪里取、缺失时如何处理 |
| 请求体 | 使用的媒体类型、字段结构与约束 | 本次客户端采用哪种输入格式 |
| 成功响应 | 对应状态与响应结构 | 业务读取哪些字段,哪些字段可以缺失 |
| 错误响应 | 文档列出的错误结构 | 如何记录错误,而不是把它当成功数据 |
| 鉴权说明 | 当前操作适用的安全要求 | 使用何种授权方式及谁负责配置 |
表格不是对工具输出字段的承诺,而是你检查转换结果时的路线。如果某项只在原规范能找到,就在交接说明注明位置;如果原规范也没有,标成待确认,不能靠 AI 补成确定事实。
看到引用,不要只保留一段名称
接口文档常把可复用定义放在别处,再在具体操作中引用。无论转换结果展示了多少内容,核对时都应沿引用找到原定义,确认字段和约束属于你正在实现的那个操作。
如果碰到外部文件、无法定位的引用,或者互相引用的结构,先列出引用原文、出现位置和缺少的材料。不要因为 Markdown 中只剩一个模型名,就把对应字段当作“不重要”或“没有限制”。也不要要求 AI 凭名字补造结构。
对同名结构尤其要核对来源。两个版本里都叫 Order,并不意味着字段完全相同。遇到多种可选结构、组合定义或复杂条件时,保留原定义位置与人工解释;没有确认清楚,就缩小本次实现范围。
这一步是资料核对建议,不表示 AIGoCode 转换器已支持或不支持某一种引用机制。工具支持情况和接口本身的语义,应该分别确认。
把“未覆盖”写成清单,不要留在脑子里
转换完后,建议给材料附一张缺口表,至少区分三种状态:已经对照原规范确认;原规范存在但摘要未完整表达;原规范本身仍待接口负责人说明。
例如你只打算先实现 JSON 查询,其他媒体类型不在本轮范围内,就明确写出。对回调、异步通知、上传或下载等任务,如果原规范涉及而本次没有核对,也应列入范围外清单。不能因阅读摘要里没看到,就断言接口没有这些行为。
同样,示例值不自动等于全部允许值。一份成功响应样本也不能证明错误分支、空值和所有枚举都已经覆盖。让 AI 遇到证据缺口时提出问题,通常比让它生成一套看似完整的默认逻辑更便于验收。
给 AI 的任务应包含明确的停点
你可以这样组织任务:只实现清单内的方法和路径;以随附原规范为定义依据,Markdown 作为阅读辅助;不得自行补造字段、认证方式或未确认的枚举;遇到引用材料缺失先列问题;先交付代码与模拟测试,不直接操作正式账户或生产数据。
这段话是任务建议,不能代替代码审查。核对生成结果时,把参数位置、请求体格式、响应读取和错误处理逐项对应回原规范。需要进行真实接口测试时,另行确认测试环境、授权与测试数据;不要把转换文档过程记成接口实测通过。
修改摘要后,保留一份可追溯的差异
人工补写的说明应与自动转换内容分清。建议单独记下补写原因、原规范位置和确认人,不只保存一个被多次覆盖的文件。再次转换时,先保留前一版,再比较变化,确认手工补充是否仍适用。
最终交付包不求文件越多越好,但要能回答:规范来自哪里、针对哪个版本、本轮实现什么、哪些尚未核实。原规范、阅读摘要和缺口清单彼此对应后,再让 AI 开始写客户端,后续审查才能沿着同一份依据进行。