「文档呢?联调要对着文档写。」前端小唐说。 「注释里都有,你自己看代码。」后端老周答。 「代码八百行,我只想知道传什么参数、返回什么结构。」 「等我发完版就补文档。」 这句话上一次说,是三个月前。会议室里两人决定把文档这事掰开,看看问题到底出在哪。
下面拿数据鱼API的「API 规范生成器」服务当例子。它的 run 端点用三个参数生成一份 OpenAPI 3.0.0 骨架,专治「文档从零开始」的拖延。
文档债是怎么欠下的
老周不是不想写文档,是启动成本太高:打开编辑器,面对一张白纸,想想八百行代码里哪些该写、怎么组织成规范文件,感觉两小时打不住,于是决定「等发完版」。等真有空了,接口细节已经模糊,只能对着代码反推,写出来的东西比代码还难读。文档债的利息,是联调时的口口相传和新人的反复提问——每问一次,都在加倍偿还。
更麻烦的是这笔债会转移:写的人省下两小时,联调的人要多花两天。老周后来算过一笔账,三个月里同一个接口被问了十七次参数格式,十七次回答加起来,够写三份文档。省下的时间没有被省掉,只是换了个地方支出。
三个参数,换一份 3.0.0 骨架
数据鱼API的规范生成器把启动成本压到接近零。数据鱼这个接口的 run 端点接收三个参数:title、path、method,而且各有默认值——不传时按标题 API、路径 /api/resource、方法 GET 处理,先跑通链路再补参数也行。GET 和 POST 调用都支持:
POST /api/api-spec-builder/run {"title": "订单查询", "path": "/api/order/query", "method": "POST"}
返回是直接可用的规范骨架:spec.openapi 标注 3.0.0,info 里带标题与版本号,paths 下按传入的路径与方法挂好节点,响应里预置了 200 的描述。文档示例传入标题 API、路径 /api/resource、方法 GET,返回的骨架里这些字段一一就位。从「面对白纸」到「面对半成品」,心理成本完全不同。
骨架里到底有什么、缺什么,两人当场列了一张表:
骨架已有 仍需手补
openapi 版本声明(3.0.0) 入参的类型与约束
info 里的标题与版本号 请求体 schema
paths 下按路径与方法挂好的节点 错误码与响应示例
200 的响应描述占位 鉴权方式与限流说明
左列是结构,右列是内容。老周看完说了句实在话:以前卡在左列,因为搭结构要记规范细节;现在左列白送,右列本来就得边写边补,反而不觉得亏。这张表也解释了为什么三个参数就够——title 决定文档叫什么,path 与 method 决定骨架挂在哪里,剩下的交给填内容的人。三个参数都有默认值,意味着连试跑都不用准备数据,先把链路走通再说。
骨架之后的活,才是文档该有的样子
骨架不解决内容,它解决「开始」。拿到骨架后,老周的活变成往结构里填:参数表、请求体、错误响应——这些本来就该边写代码边补,而不是事后凭记忆反推。小唐再也不用翻八百行代码,联调对着规范文件,路径、方法、响应结构一目了然。
两人后来定了个新约定:接口合入前先跑一次生成,把骨架提交进仓库;细节可以暂时空着,但不能没有骨架。约定还补了两条细则:生成命令写进仓库脚本,参数从路由表取,避免手抄路径抄错;method 统一大写,生成前顺手校验一遍,别让一个小写的 get 变成规范文件里的怪节点。从「写文档」到「补文档」,差的不是勤奋,是一个足够低的起点。
以上端点、参数与返回结构说明,整理自数据鱼API「API 规范生成器」接口的公开文档;示例参数与返回均为文档演示数据。