API 文档的质量之争：自动生成、手写指南、OpenAPI-first，你的团队站哪边？

背景

做了 8 年技术文档，这两年帮 4 个后端团队做过文档体检。一个反复出现的现象让我想拿出来聊：同一个团队，对外 API 的「文档质量」差距可以大到让集成方怀疑是不是不同公司发的 SDK。

我复盘过的典型事故，根因都不是「没写文档」，而是「文档写了，但写错了 / 写旧了 / 写得没法用」：

• 一个支付对接团队，文档里 amount 字段写的是「元」，实际接口收「分」——文档生成自旧版 OpenAPI，代码改了、文档没跟上，集成方按文档调，直接资损演练；
• 一个内部网关，Swagger 自动生成的字段描述全是 description: null，集成方只能「看代码猜语义」；
• 一个 SDK 的 changelog 和文档版本对不上，用户装了 v3 还在看 v2 的示例。

几种常见做法（也是分歧所在）

做法 A：OpenAPI-first，文档从 spec 生成。 工具链成熟（Swagger / Redoc / Stoplight），spec 进仓库、走 review，文档天然和代码同步。代价：spec 的「描述字段」质量完全依赖写 spec 的人——很多人把它当类型声明用，描述一栏空着。

做法 B：文档工程师手写指南，接口字段交给工具。 手写「场景化接入指南」（怎么调、报错怎么办、坑在哪），字段级文档自动生成。代价：两套东西要人肉对齐，spec 一改、指南就可能漂移。

做法 C：完全手写 markdown，不引入 spec 工具链。 灵活、自由，但「代码和文档一致性」完全靠自觉，团队一忙就烂尾。

做法 D：文档即代码（Docs as Code），markdown 进仓库走 CI。 比 C 多了 review 和 CI 校验，但字段级语义仍然手写。

我的倾向与理由

我倾向 A + B 组合：字段级语义强制进 spec（描述、单位、枚举含义、错误码），CI 校验 spec 描述的完整性（空描述直接 fail）；场景化指南由文档工程师手写，但只引用 spec 的字段名、不复制字段定义——避免「两处定义」。

理由从现象倒推：上面三个事故里，两个是「字段语义漂移」，一个是「版本漂移」。字段语义和代码同源（spec），版本用 CI 卡死，漂移面就小得多。场景化指南是工具生成不了的部分（「你的业务场景下该怎么组合调用」），必须人写。

想听大家聊聊

1. 你们团队的 API 文档是哪种做法？踩过什么坑？
2. spec 描述字段的「质量门槛」你们怎么定？有没有在 CI 里卡「空描述」或「描述过短」？
3. 手写指南和自动生成文档「两处定义」的漂移问题，你们怎么解决？
4. 有没有人试过用 LLM 辅助补全 spec 描述？效果如何，会不会引入「看起来对、实际错」的幻觉描述？
5. B 端对外 API 和内部 API，文档策略要分开吗？

欢迎把你们团队的真实做法和踩坑贴出来，越具体越好——工具链、CI 配置、文档目录结构都行。