接口文档没人看：DeepSeek 补 12 个调用示例

一份接口文档，12 个接口，每个都列了参数名、类型、是否必填。看着挺规范，但没人看——因为开发者点进来想知道的是「我怎么先跑通一个」，而文档里没有一行可以直接复制执行的代码。

一句话结论

文档没人看，通常不是写得差，是「读完能得到什么」不清楚。补示例是最直接的修法，但有个前提：AI 生成的示例必须真跑一遍，实测 12 个最小可用示例里有 3 个跑不通（25%），错误都是参数类型写错或漏了必填 header——这种错在文档里看着完全正常。另外加错误示例时还顺手发现了 2 个接口本身的校验缺陷。

这篇解决什么问题

三种情况最常见。一是只有参数表没有前提：文档写了每个接口要传什么，但没写鉴权头放在哪、base url 是什么版本、时间戳用秒还是毫秒。开发者照着参数拼了半天，卡在 401。二是示例是伪代码：写成 `GET /api/v1/orders?status=xxx`，变量用 xxx 占位，看着清楚但没法执行，开发者还得自己补参数、补头、补编码。三是示例是对的但缺错误分支：正常路径跑通了，一遇到 400 就不知道是参数错还是权限错。

根子是把文档当成「说明书」，而开发者要的是「能跑起来的最短路径」。所以补示例不是锦上添花，是把文档从「查阅型」变成「上手型」——顺序上，公共前提、最小示例、错误示例，三样齐了才算能上手。

开始前要准备什么

• 12 个接口的完整定义：路径、方法、参数（含类型与必填）、返回结构。返回结构尤其重要，示例的输出部分要靠它校验。
• 一个能真实调用的测试环境，以及一组可用的测试凭证。没有可跑环境，示例只能靠猜。
• 当前文档的访问数据（如果有）：哪个接口页停留时间长、哪个跳出率高。这能定出补示例的优先级。
• 一条纪律：每段示例都要真跑，记录实际返回。凭 AI 生成的样子交付，等于把坑转给开发者。

具体怎么做

第一步：先把公共前提单独抽出来

12 个接口有大量重复的前提：鉴权方式、base url、版本头、内容类型、时间格式。这些不抽出来，每个示例都要重复一遍，而且容易漏——漏一个头，示例就跑不通。

抽出来的部分放在文档最前面，叫「先做这三件事」：拿到 token、设好 base url、确认时间格式。实测这三条补齐之后，开发者卡在 401 的问题少了大半（原本 12 次咨询里有 7 次是鉴权问题）。

这是我 12 个接口的定义（路径、方法、参数、返回结构）。我要重写文档，先抽出公共前提。

请做三件事：
1. 找出 12 个接口共有或几乎共有的前提条件（鉴权方式、base url、版本头、content-type、时间与编码格式、分页约定），逐条列出，并说明从哪几个接口的定义里看出来的；
2. 把这些前提写成一段「先做这三件事」的开头，要求是开发者照做就能发出第一个成功请求；
3. 指出哪些前提在现有定义里写得含糊、需要我去确认（比如时间戳单位没写明），列成待确认清单。

要求：不要编造我没提供的约定。定义里没写的，进待确认清单，不要猜。

第二步：每个接口一个最小可用示例，能直接粘

「最小可用」的标准是：去掉一切可选参数、只保留必填项、能返回一条真实数据。示例形式用 curl，因为 curl 最容易被复制到任何语言里改。每个示例都要带三部分：完整命令、真实返回（截断到关键字段）、一句话说明这段在做什么。

变量不要用 xxx 占位，要用能跑的具体值（测试环境的真实 ID）。占位符看着干净，但开发者得自己找值，这一找又会卡一次。

按上面的公共前提，给这 12 个接口各写一个最小可用示例。

每个示例包含：
1. 完整 curl 命令（含全部必要 header，参数用测试环境的真实值，不要用 xxx 占位）；
2. 预期返回：只保留关键字段，用 JSON 表示，并标注哪些字段是每次都变的值（如时间、ID）；
3. 一句话说明：这个接口干什么、什么场景下用；
4. 常见踩坑一行：这个接口最容易写错的一个参数，写清错在哪。

硬要求：
– 只用必填参数，可选参数一个都不要加；
– 如果某个接口必须传可选参数才能返回数据，单独标出来说明原因；
– 参数类型必须与我给的定义一致（数字不要加引号、布尔不要写字符串），逐条自查后告诉我自查结果。

第三步：真跑一遍，把失败原因分类

这一步不能省。实测 12 个示例跑下来 9 个通、3 个不通：2 个是参数类型错（把数字写成了字符串，接口做了严格类型校验）、1 个是漏了必填的版本头。这三处如果直接上线，会变成三张工单。

失败原因要分类记：类型错、缺必填、值不合法、路径拼错。分类之后你会发现规律——类型错最多，因为 AI 生成 JSON 时习惯给所有值加引号。

这是 12 个示例的实际执行结果（含成功的返回和失败的报错原文）。请帮我做失败归因。

对每个失败的示例：
1. 报错原文里能看出什么（错误码、错误信息的关键词）；
2. 归因：类型错 / 缺必填 / 值不合法 / 路径拼错 / 环境问题；
3. 修正后的命令（只改出错的那一处，其他不动）；
4. 这个错该不该写进「常见踩坑」——如果开发者很可能犯同样的错，就写；如果只是我这次手误，就不写。

然后做一次横向统计：12 个示例里按归因分类各几个，哪一类占比最高。最后给我一条「生成示例时该提前自查什么」的规则。

第四步：加错误示例，只加最常见的三种

错误示例不是越多越好，只加开发者最可能撞上的三种：鉴权失败、必填缺失、值超出范围。每种给一条命令、一段真实报错、一句话解释「看到这个报错该改哪里」。

意外收获：写错误示例时故意传了非法值，发现有 2 个接口没报错而是返回了空数据——这属于接口本身的校验缺陷，被顺手记进了缺陷清单。这类发现只有真跑才会出现。

给这 12 个接口补错误示例，只要三种：鉴权失败、必填缺失、值超范围。

每种包含：
1. 一条能触发该错误的完整命令；
2. 真实报错返回（原样，不要美化）；
3. 一句话：看到这个报错，改哪里。

另外帮我做一件事：对每个接口，判断「传非法值时它会不会安静地返回空数据」——如果会，说明校验有缺口，列进缺陷清单并写明影响（开发者会以为查无数据，实际是参数错了）。

不要构造我没验证过的报错。没跑过就标「待验证」。

实测记录

素材是内部一套订单类接口，12 个接口，原文档只有参数表与返回字段说明。第一步抽公共前提 15 分钟，抽出 6 条共有约定、4 条待确认（其中时间戳单位最要命，文档没写，实测是毫秒）。

第二步生成示例 20 分钟，12 条 curl。生成时有意识地要求「只用必填参数、用真实值不用占位符」，这一步省了后面很多沟通——原来文档里写 `?status=xxx`，开发者得自己猜 status 有哪些合法值。

第三步真跑 45 分钟，9 通 3 不通。失败归因：类型错 2 个（都发生在 JSON body 里，数字被加了引号）、缺必填 1 个（漏了版本头）。修正各花 2 分钟，但找原因花了 20 多分钟——其中一个报错信息只写了「参数错误」，没说是哪个参数，靠逐个注释掉试出来的。

第四步错误示例 20 分钟，补了三种共 6 条（每种 2 条，覆盖有 body 和无 body 两种接口形态）。过程中发现 2 个接口对非法值不报错，直接返回空列表——已记进缺陷清单，这类问题不真跑永远发现不了。

全程 100 分钟。改完之后两周内，关于「怎么调这个接口」的咨询从每周 7 次降到 2 次，剩下的 2 次都是业务规则问题，不是调用问题。

最容易错的 3 个地方

第一，用占位符写示例。`xxx`、`{id}`、`your_token` 看着规范，但开发者要自己去填，填的过程又是一次卡顿。用测试环境的真实值，让他复制就能跑，这是「上手型文档」和「查阅型文档」的分界线。

第二，示例不真跑。AI 生成 JSON 时习惯给所有值加引号，这个习惯在严格类型校验的接口上必挂。实测 25% 的示例有这类问题，而它们在文档里看着完全正常。跑一遍 45 分钟，能省掉三张工单。

第三，错误示例只写报错不写改法。给一段 400 报错，开发者还是不知道该改哪。错误示例的价值在后半句：看到这个错，去改哪个参数。没有这半句，等于把问题又踢回去。

可复用的东西

公共前提六条：鉴权头位置、base url 与版本、content-type、时间格式与单位、编码方式、分页参数。抽到文档最前面。

最小示例四要素：完整命令、真实返回（标出会变的字段）、一句话用途、一行常见踩坑。

只用必填参数。必须传可选参数才能返回数据的接口，单独标注原因。

失败四归因：类型错、缺必填、值不合法、路径拼错。类型错通常占第一。

错误示例三种：鉴权失败、必填缺失、值超范围。每种都要写「改哪里」。

校验缺口检查：对每个接口传一次非法值，看它是否安静返回空数据。

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

admin 普通

收藏 海报 链接