猜您喜欢：：不锈钢清洗剂介绍-不锈钢清洗剂介绍 空乘艺考示范视频-空乘艺考示范短视频 法语考研辅导班学费-法语考研辅导班收费 梦见给人接生小孩有什么预兆-梦见接生小孩预兆 高级等级证书查询(高级证书查询) 质量体系认证标志(质量认证标志) 彪马在哪个国家火-彪马起源二 青春期孩子家长的感悟-青春期家长感悟 什么是可可-什么是可可 机电二级建造师吊车-机电二造吊车证书
大量人当作写 API 文档是发代码，实际上那是给机器看的。真正干活的是那些整天跟数据库和缓存吵架的架构师，要么是负责把后端变得“不那么丑”的前端开发者。他们最头疼的不是接口地址，也不是 HTTP 状态码，而是那个一辈子回不来、吞掉所有参数、要么根本不管我有没有连上网关的接口。 实际上写 API 文档的源头大多在产品经理手里。你们在盯着高并发下的吞吐量，盯着极端情况下的延迟，盯着那些为了应付面试官随口编出来的边界值。你们在争论要不要加个 500 状态码，要不要把密钥放在 Header 里还是 Body 里，就连要不要为了演示效果把服务器秒开再秒掉。产品经理的文档往往是干巴巴的列表，参数名是驼峰，毛病码是整数，把 CRUD 操作全塞进一个 JSON 里。 然后就是架构师和开发人员干活的环节了。这时候的文档启动变得面目全非。架构师脑子里想的可能是缓存穿透、雪崩要么消息队列的积压，但这些玩意儿如何跟 HTTP 接口挂钩？他把这些概念翻译成“超时”、“限流”、“重试策略”，然后扔给文档工具，工具再给出一堆标准格式字段。开发人员则是另一拨人，他们更关心代码能不能跑通，能不能在毫秒级响应页面。便乎，前端工程师启动为了展示效果，硬是把 Server-Sent Events 加上了，为了体现“极致”，在参数里放了个 `x-weather: 1999`，结局给文档看的时候又把 `Content-Type` 改成 `application/x-www-form-urlencoded`，搞得一团糟。 文档的工具选型也是个庞大的坑。你是在用 Swagger 写，还是在用 Postman 的 JSON 描述？Swagger 本身挺美，能自动生成 OpenAPI 3 的规范，但它往往只能处理最好办的 CRUD 场景，对于复杂的网关路由、中间件配置、异步任务编排，它就是个死板的数据模型。
这时候就得靠手写了。XML 文档目前越来越冷，JSON 别看流行但忒散，你写起来像在写代码注释。
这时候往往是那种叫“文档流”要么“富文本编辑器”的工具，你得先定义好 Schema，然后手动拼接字符串，最终还得去那个网页上跑一遍 Postman 测试，看一遍浏览器管住台有没有报错，参数填对没，然后再改回去。 我见过最夸张的案例，就是中午 12 点，产品经理告诉架构师：“把这个参数改一下。”架构师带着参数跑了一遍，发现响应工夫从 50ms 变到了 300ms，还得加个延时处理。最终架构师没理他，直接把旧文档改成了新的格式，改了个 XML 标签，改完就直接发给了前端。前端收到文件一看，格式不对，报错了。前端没空去问后端，直接写了个自定义的 JSON 注解，拼进了前端代码里。结局上线了，后端查数据库，前端直接读这个怪异的 JSON，全链路都崩了。 这类文档一般分两层写。底层是技术债，是系统稳定运行的基石，不管哪位提意见，最终都归他管；上层是业务线，是产品经理和前端看的，他们认定参数要如此填才好看，不让他懂技术就改不了。
这两层时常打架，害得文档一辈子处于半崩状态。 有时候文档写得挺不错，参数都定义清楚了，就连带点业务逻辑的描述，比如“必填且不能为空”、“务必包含 xxx 字段”。但难题在于，这个文档对哪位有效？是给那帮用 Postman 查参数的 QA 看的，还是给那些天天改代码的开发者看的？大量时候，文档里写的参数，连为啥如此写都说不清。 数据量也是难题。API 文档本身就不该包含所有的数据，那只是数据库和缓存的截图。真正的文档应当只描述“骨架”，告诉对方接口长啥样，参数有哪些，如何传，有啥限制。至于具体的字段内容、业务逻辑、数据转换，那是运行时才知道的。
要是文档里塞进所有数据，哪怕再漂亮，那也是误导。 故此，写 API 文档这事儿，本质上是一场信息同步的战役。产品经理拍板了我们要做啥，架构师拍板了能不能做，前端拍板了如何显示，而写文档的过程，就是把这三者的需求，拆成一个个能放进 Swagger 要么 XML 框里的 JSON 字段。它不追求完美，出于它本身就是一个不断被推翻、被重写、被各种意外推翻的过程。最理想的文档，不是那个引用率为 0 的文档，而是那个文档根本没人去维护，要么每次维护都只改了极少一局部的文档，剩下的逻辑已经被团队内部默契地套上了。 最终写文档的人，往往就是那个最“没经手”的人。他可能没写过一行后端代码，也没见过一次数据库迁移，但他务必知道接口要回啥格式，要处理哪些异常，否则文档就写不出来。他的价值不在于代码，而在于让所有人理解同一个接口意味着啥。
要是文档写得忒难懂，要么忒专业，开发团队就会绕着它转，最终连文档本身都写不下去了。
这时候，技术本来就难，文档更难了。
好文推荐：：盘龙城哪家装修公司好-盘龙城装修公司选哪家 梦到npy出轨了意味着什么-梦到出轨反映现实 遵义哪家装修公司最好(遵义优质装修公司) 网站设计的好的公司(好网站公司) 彪马在哪个国家火-彪马起源二 青春期孩子家长的感悟-青春期家长感悟 外事管理专业介绍(外事管理专业介绍) 孔板的流量计工作原理(孔板流量计原理) 如何查飞机到哪了-飞机定位查询 专业教育与介绍讲座听后感-专业讲座听后感
转载请注明：api文档一般是谁写-文档通常由开发者编写
相关标签：