用Claude自动生成内部API文档

简而言之： 先用确定性的方式从代码库里抽出路由表，再让Claude只去描述这些端点——参数、响应、错误语义——并在每次合并时通过CI重新生成。把模型锚定在一份真实清单上，正是它不会凭空编出端点的原因。而第一次跑完，通常会翻出一些没人知道还暴露在外的东西。

每个工程团队都有同一份文档。它在服务上线时被认真写过，准确了大约五周，如今它描述着三个已经不存在的端点，同时漏掉了此后新增的十一个。没人信它，所以没人更新它，于是它继续腐坏。新人干脆去读源码——而这恰恰是那份文档本该避免的事。

这种腐坏是结构性的，不是文化性的。文档活在一个系统里，变更发生在另一个系统里，只有当某个人注意到差距时，两者才被连起来。这正是语言模型擅长的那类机械的、高上下文、低判断的工作——前提是你约束住它被允许声称什么。

为什么内部API文档总是最先腐坏？

内部文档比对外文档腐坏得更快，原因值得点名，因为每一条都会影响你怎么做自动化。

没有外部压力。 一个对外API的文档写错了会伤到客户。一个内部API写错了只会绊住同事，而同事会走过来问一句，于是绕行方案变成口口相传的部落知识，而不是一次文档修正。

作者会离开。 内部服务往往由一两个人写成，整个模型装在他们脑子里。等他们换了团队，文档就不再是"共同理解的摘要"，而成了唯一的记录——偏偏就在没人维护它的那一刻。

文档不在"完成的定义"里。 合并需要测试和评审，却很少要求更新文档，所以文档在设计上就永远慢一步。

没人知道端点的真实数量。 服务会积累调试路由、内部管理路径、某个被人扩展过的健康检查，以及一个已废弃却从未被移除的功能的端点。任何从"人们记得什么"开始的文档工作，都是从一份不完整的清单开始的。

最后这一点最要紧，它改变了解决方案的形状：目标不是更快地写出散文，而是让端点清单从代码本身推导出来，这样文档就无法悄无声息地漏掉没人记得的东西。

Claude究竟能从代码库里生成什么？

端点参考、示例与错误语义

给定一个路由处理函数和它触及的类型，模型能稳定产出描述层：这个端点是干什么的、每个参数是什么意思、一次真实的请求和响应长什么样，以及代码实际会返回哪些错误。按篇幅算，这是API参考文档的主体，也是工程师最不愿意写的部分。

它同样擅长那些手写文档会跳过的连接组织。哪些端点需要哪种认证。分页约定是什么。哪些字段可为空、在什么条件下可为空。某个操作是否幂等。这些都能从代码里读出来，但手工汇编起来很烦，而它们的缺失，正是让一份参考文档"技术上完整、实用上没用"的原因。

两条诚实的边界。第一，模型描述的是代码做了什么，不是它应该做什么——如果实现与预期契约相矛盾，你拿到的是对这个bug的文档。第二，它无法知道未被写下的业务上下文：某个字段为什么存在、哪个调用方依赖着那个奇怪的行为，或者某个参数因为一个配置开关在生产环境里其实被忽略了。这些依然只能来自人。

事实来源应该是代码、规范，还是两者？

多数框架已经能从注解或类型定义生成OpenAPI规范，而那份机器生成的规范，是一个比"模型读文件"好得多的地基。它在构造上就是穷尽的，也不可能幻觉出一条不存在的路由。

所以两者都用，但顺序要对。用确定性的方式生成或抽取规范——从框架注解，或通过解析你的路由定义——并把它当作端点及其形状的权威清单。然后把它连同相关的处理函数代码一起交给模型，要它给出描述、示例和行文。模型负责丰富，不负责枚举。

这个顺序是整条管线里最重要的一个设计决定。一个被要求"给这个仓库写文档"的模型，会产出看起来很合理、但并不存在的端点，而正是这份合理性让它们在评审里格外难被抓到。一个被要求"描述这十四个端点，如果代码不清楚就明说"的模型，是在一个它无法绕开的事实之内工作。

一条务实的管线：生成、评审、发布、重新生成

从"每次合并到主分支时抽出路由表"开始。框架工具、构建期的规范生成器，或者一个解析路由文件的小脚本——只要它是确定性的就行。这个产物就是契约。

把它与上一次的结果做差异比对。多数合并不会改变任何相关的东西，而只为变化的部分重新生成行文，能让成本和评审负担保持在合适的比例上。一个新端点、一处签名变更、一条被移除的路由，会触发工作；一次不触及任何接口的重构，不会。

对每一个变化的端点，把规范条目、处理函数源码、它引用的类型，以及已存在的旧描述一并交给模型。要求它在人写的内容仍然准确时予以保留、在不再与代码相符时予以标记，而不是直接覆盖——否则每一段精心写下的解释，都会在下一次运行时被换成千篇一律的行文，然后团队就不再写它们了。

然后经由评审发布，而不是直接发布。管线应当向文档仓库或你的wiki提一个PR，而不是无人看管地提交生成内容。这以很低的成本把人留在环里，给你的是一份可以扫一眼的差异而不是一份要通读的文档，也意味着一次糟糕的生成是一个被拒的PR，而不是一处已发布的错误。文档放在哪里，远不如"它是被生成出来的而不是被记住的"重要——同样的原则，我们在用Claude保持Confluence文档同步那篇里也讲过。

AI生成文档 vs 规范优先工具 vs 手写文档

覆盖度 — 规范优先工具完胜。它在构造上就记录了每一条路由，而纯模型方案只记录了你给它看过的，手写文档只记录了某个人记得的。
可读性与有用性 — AI生成胜出。一份原始的OpenAPI渲染只告诉你某个字段是字符串；有用的版本会告诉你该往里放什么、放错了会发生什么。
端点清单的准确性 — 规范优先胜出，而这是最要紧的一项。绝不要让模型成为这份清单的来源。
保持最新 — 规范优先和AI生成都胜过手写，因为两者都会自动重新生成。手写文档只在某一个瞬间是准确的。
捕捉意图与业务上下文 — 手写胜出。一个端点为什么存在、哪个调用方依赖它的怪癖，这些都不在代码里。
搭建投入 — 短期看手写胜出；如果你的框架支持，规范优先是中等投入；而一条带CI集成和评审流的完整AI管线，是其中最大的一笔投入。

真正行得通的组合是三者并用：规范优先负责清单，AI负责描述，人负责意图——并且让管线保留人写的内容，而不是把它们碾平。

它会暴露什么——以及为什么那才是真正的价值

这样一条管线的第一次完整运行，通常比它产出的文档更有意思。

没人记得的端点。 两年前某次故障留下的调试路由、为一次性迁移加的管理路径、本该在v2上线时下线的v1。每一个都是活着的、可达的暴露面。

缺失或不一致的认证。 "汇编出哪些端点强制了哪些检查"这件事，恰恰是那个会暴露出"中间件从未被应用到那个处理函数上"的动作。这很少是恶意的，几乎总是一次把路由从守卫后面挪出来的重构。

示例和测试夹具里的密钥。 生成示例请求的模型，依据的是你给它看过的东西，而测试夹具里满是看起来很真的令牌——有时候它们就是真的。发布前请扫描生成结果里的凭据模式，并把找到的任何东西都当作一个需要立即轮换的活密钥。

未被写下的"仅内网"假设。 那些因为"只有内网能访问到它们"而被认为安全的端点，而这是某人在三次架构变更之前对网络拓扑作出的判断。

面对一份"被遗忘的、可能未认证的端点"清单，诚实的回应不是一个wiki页面，而是去测试它们是否真的可达、暴露了什么——那正是渗透测试的用途。文档告诉你你有什么，只有测试才告诉你它是否安全——而"我们刚发现四十个没人记得的端点"，是预约一次渗透测试的相当充分的理由。

把这件事做对：源码保密、API密钥，以及何时该让IT介入

把专有源代码发给第三方模型是一个真实的决定，不是一道手续，它值得一个刻意给出的答案，而不是工程师在当下的个人判断。

去读适用于你所用那个具体层级的条款——商业版和API层级在留存与训练上通常与消费级产品不同，而且条款会变，所以请以当前文档为准，而不是某位同事的记忆。然后决定范围：很多组织能接受发送应用代码，但坚决不接受发送任何来自"存有客户数据夹具、密码学材料，或受客户保密条款约束的代码"的仓库。把这条边界写下来，因为另一种选择是每个工程师各自私下决定。

机制层面同样要紧。这条管线需要一个仓库令牌和一个模型API密钥，它们活在CI里。请使用短生命周期、最小权限、且限定到具体仓库的凭据，把它们放进CI服务商的密钥库而不是配置文件，并按一个真的有人负责的周期轮换。一条拥有全组织范围读权限的生成管线，本身就是你攻击面上不容忽视的一块。我们的AI+支持服务负责在搭建这类工具时从一开始就把这些控制放进去，而托管IT支持则在不止一个团队依赖它之后，接手围绕它的身份、权限与密钥生命周期。Brocent自2007年在北京创立以来一直在亚洲提供托管IT服务，总部位于新加坡，并自2016年起设有香港办公室。

常见问题

把专有源代码发给AI模型安全吗？

这取决于层级和代码本身，而且它应该是一个被记录下来的决定，而不是每位工程师各自的判断。请查清服务商当前条款就你所在的具体方案在留存和训练上的说法，并对"哪些仓库可以走这条路"设一条明确边界——应用逻辑，和一个包含凭据、客户数据夹具或受客户保密义务约束的代码的仓库，是完全不同的两个问题。

它会幻觉出不存在的端点吗？

如果你让它来枚举，会。这正是为什么路由清单必须来自确定性的抽取——框架的规范生成，或解析你的路由定义——而模型的职责被限制在描述这份清单上的条目。这样约束之后，"编造端点"就不再是一个现实的失效模式。

怎么让文档与代码保持同步？

在CI里以"合并时触发"来重新生成，而不是靠定时任务或手动。对抽出的规范做差异比对，只重新生成变化的部分，并提一个PR供评审。任何需要某个人记得去跑一下的东西，一个季度之内就会漂移。

它找出来的、没人记录过的端点该怎么办？

先分诊，不要急着写文档。对每一个，弄清楚它是否仍在被使用、它强制了什么认证、它暴露了什么。把死的移除，把活的加固，然后才写它。给一个未认证的、被遗忘的端点写文档，只是把它更清楚地公布出去。

它会覆盖我们工程师写的解释吗？

只有当你把它做成那样时才会，而这正是那个会扼杀采用率的失效模式。把已有的描述作为上下文传进去，并指示模型：保留准确的人写文本、标记不再与代码相符的部分、只补上缺失的内容。如果工程师看到自己的解释被换成千篇一律的行文，他们就不会再写了。

这能取代OpenAPI规范吗？

不能——它依赖于规范。规范是那份权威的、机器可读的契约，同时还驱动着客户端生成和测试。这条管线是在它之上加一层人类可读的东西，而那正是原始规范渲染做得不好的部分。

从哪里开始

挑一个服务，最好是一个大家会抱怨的、中等规模的内部服务。用确定性的方式抽出它的路由表，把这份清单与现有的任何文档做比较——通常正是这一次比较，让这个项目拿到了预算。然后为通过分诊的端点生成描述，把重新生成接进CI并走PR，并且在把范围扩大到其他仓库之前先把凭据权限定好。如果第一次运行翻出了一些没人说得清的端点，而你更希望知道它们实际暴露了什么、而不是靠猜，欢迎联系我们。