把接口文档丢给 AI 生成调通代码，附一张参数说明表

一句话结论

把接口文档连同真实请求样例喂给 AI，按生成、校验、回填三步走，通常 20 分钟内能拿到可跑的调用代码和参数说明表。

这篇解决什么问题

对接第三方或兄弟团队的接口，最耗时的不是敲代码，是从几百行文档里把参数、必填项、鉴权方式一条条抠出来，再对着一堆 400 报错反复试。这篇讲的是我在实际对接中怎么把这段活拆给 AI 做。

适用：文档有结构、能拿到至少一段真实请求样例的 HTTP 接口。不适用：文档只有截图没有文字，或者接口本身还在频繁改版本、今天写明天废的场景。

开始前要准备什么

• 一份能打开的接口文档，内部 wiki 或对方给的 PDF 都行，先确认版本日期
• 一段真实请求样例：抓包、日志或同事给的 curl，脱敏后再用
• 豆包或 DeepSeek 任选一个，日常问答的免费额度够用；Cursor 可选，用来落代码
• 本地能跑通的最小工程，Python 或 Node 都行，装好 requests 或 axios
• 预计耗时：单个接口通常 20 到 40 分钟，鉴权复杂的再加一刻钟

具体怎么做

第 1 步 · 按接口切文档，别整份丢进去

我在实操中发现，AI 拿到一整份文档时，注意力基本集中在前两三个接口上，后面的开始自己编。所以先切块，一个接口一段对话。

你是接口对接助手。我会分次把一份接口文档的段落发给你，这一次你只做一件事：确认这段文档覆盖的是哪个接口，并把它的边界标出来。请输出三行：1. 接口名 + 请求方法 + 路径；2. 这段文档里出现的参数总数，query、path、header、body 分开数；3. 这段文档里没交代清楚的地方，最多列 5 条。先不要写代码，也不要总结文档内容。如果我贴的内容里混进了别的接口，直接指出来让我重新切。文档片段：”””【把文档里属于这一个接口的段落粘在这里】”””

预期产出：一段几十字的确认，告诉你这段文档属于哪个接口、有多少参数、哪些地方含糊。切错了当场就能发现。

第 2 步 · 先要参数表，不要代码

很多人习惯上来就让它写调用代码，写出来看着挺像，一跑全是错。顺序反过来，先逼它把参数表列全，错误在这一步就暴露了。

基于上一条里那个接口的文档，现在生成一张 Markdown 参数说明表。列固定为：参数名 | 位置 | 类型 | 是否必填 | 取值范围/枚举 | 默认值 | 文档是否写清 | 备注。规则：1. 嵌套对象和数组展开成多行，层级用 a.b.c 表示，数组用 items[].field 表示；2. 文档没写、你也不确定的行，在「文档是否写清」列填「否」，默认值列留空，不要编一个看起来合理的值填进去；3. 表格后面单独加一段「对接风险清单」，只写三类：鉴权方式、时间字段的格式和时区、分页或批量上限，文档里没提的也要点出来并标注「文档未提」。示例数据里的商户号用 merchant_demo，密钥用 sk_test_xxx 占位，不要用真实值。

预期产出：一张能直接贴进对接文档的参数表，加一段风险清单。风险清单往往比表本身值钱，它是你和对方沟通时要问的问题列表。

第 3 步 · 用一段真实请求，把文档缺口逼出来

文档写的字段和接口实际校验的字段，经常不是一回事。拿一段线上或者测试环境跑通的请求喂回去，让 AI 做逐字段比对，这比追问文档作者快得多。

下面是我从日志里抓到的一段真实请求，已脱敏，对应的就是上面那个接口。请做两件事：1. 逐个字段对照参数表，指出请求里出现但表里没有的字段、表里标必填但请求里缺失的字段；2. 结合这段请求，修正参数表里「文档是否写清」标为「否」的那些行，每一条都要给出推断依据，依据只能来自这段请求或文档原文，不能来自你的经验猜测。真实请求：”””POST /open/api/v2/order/create
Host: api.example-internal.test
X-Sign: ****
Content-Type: application/json
{“merchantId”:”merchant_demo”,”items”:[{“skuId”:”A1001″,”qty”:2}],”payType”:”WALLET”,”extra”:{“remark”:””}}”””

预期产出：一份修正后的参数表，以及一张「文档没写但实际存在」的字段清单。这份清单我会直接发给对方确认。

第 4 步 · 生成能直接跑的最小代码

到这一步才让它写代码。约束给得越死，出来的东西越好用，尤其别让它上分层和抽象基类，那种代码你改起来比重写还累。

用 Python 写一个能直接跑的最小调用脚本，对上面这个接口发一次请求。约束：1. 只用 requests，不引入其他第三方库，Python 3.9 以上；2. 把所有可配置项提到文件顶部的常量区：base_url、merchant_id、app_key、app_secret、timeout；3. 签名逻辑单独写成一个函数，函数上方用注释写清楚签名串的拼接顺序，如果文档没写清楚，就用我给你的那段请求反推，并在注释里标「推断，未验证」；4. 请求前后各打一行日志：发出去的 body（密钥脱敏）和返回的 status 加前 300 字响应体；5. 不要写类和抽象层，一个文件跑到底。代码写完，在下面用一段话告诉我：这段代码里哪几行是我必须自己核对文档才能确认的。

预期产出：一个能直接执行的单文件脚本，加一段「需人工核对」的说明。那几行大概率就是签名和鉴权头。

第 5 步 · 真跑一遍，让 AI 按报错自己改

把真实报错贴回去，比你自己读代码猜要快。关键是加一句「信息不足就说需要什么，不要猜着改」，能挡掉一半的胡乱修改。

我按你上面给的代码跑了一次，返回如下。状态码：400。响应体：”””{“code”:”PARAM_INVALID”,”message”:”payType not support”,”traceId”:”t-9f2c”}”””请做三件事：1. 先说这个错误最可能出在哪一行，给出判断依据；2. 给出修改后的完整代码，不要只给 diff，我要能整段替换；3. 如果这个错误说明参数表里某一行的取值枚举写错了，同步把参数表那一行改回来。如果信息不足以判断，直接说需要我再抓什么，不要猜着改。

预期产出：一份改好的完整代码，同时参数表被同步修正。代码和表始终是同一版，后面交接不会打架。

实测记录

成本这块没什么可说的，都在工具的免费额度里跑完，一个接口的对话轮次通常不超过十轮。失败情况也有：有一次文档是截图版，AI 认错了两个字段的类型，生成出来的代码直接把数组当字符串拼，这个坑只能靠第 3 步的真实样例兜住。

最容易错的 3 个地方

1. 整份文档一次丢进去，AI 只挑前面几个接口答。改成按接口切块，一问一接口。
2. 让它先写代码再补参数表，表必然漏项。顺序反过来，先表后码。
3. 直接信 AI 填的默认值和必填项。拿真实请求回灌，报错才是准的。

可复用的东西

上面五段提示词其实是一套固定的流程：切块、出表、回灌、生成、纠错，每一段都把「不要猜」写死在约束里。你可以把这五段存成自己的片段库，换个接口只改三处：接口名、文档段落、真实请求样例。

参数表那一段的列定义建议原样保留，「文档是否写清」这一列是整个流程的抓手，删掉它，AI 就会开始自作主张地补默认值。

对接这件事本身没什么捷径，能让 AI 替你干的，是那些翻文档、对字段、抄签名的机械活。你手上那份接口文档，是参数漏写得多，还是鉴权写不清得多？

如果你也经常要做这件事，欢迎在评论区说说你的卡点和做法；也可以留言告诉我，你想看哪个岗位的哪件活怎么用 AI 拆。

admin 普通

收藏 海报 链接