Vibe Coding API 文档同步：从发布制品生成，再由契约样例反证

API 文档漂移有两种相反形态。代码优先团队改了 handler，却忘记重新导出 reference；设计优先团队更新 OpenAPI 并成功生成页面，服务端仍运行旧实现。两边都可能在 CI 看到“文档构建通过”，用户却按不存在的字段、错误码或鉴权方式接入。AI 同时修改规范、实现和示例时，这种共同漂移更难被普通测试发现。

本文不讨论如何把文档站接入问答，也不重复OpenAPI 契约优先集成中的客户端与服务端生成流程。目标只有一个：公开的 API reference、用户看到的版本入口和实际响应，是否属于同一代经过验收的接口。

先选唯一规范身份，不争论唯一写法

团队可以 code-first 导出规范，也可以 spec-first 生成骨架，但每个发布只能有一个被批准的 canonical contract。它包含 OpenAPI 版本、文档自身版本、内容摘要、生成工具版本、源码提交和适用服务制品。构建目录里的临时 JSON、运行端点动态吐出的 schema 和文档仓库副本不能同时被当作权威源。

OpenAPI 3.1 使用 JSON Schema 2020-12 方言表达 Schema Object，但协议仍有自己的语义；“JSON Schema 校验通过”不等于 operation、状态码、媒体类型和安全要求完整。HTTP 方法的安全性、幂等性、缓存等含义应服从 RFC 9110，不能由 AI 根据函数名猜测。业务约束如额度、状态转换和重复请求结果则必须作为明确描述和契约样例存在。

发布清单为规范生成稳定 contract ID，例如服务名、公开主版本和摘要。文档生成器只接受清单引用的规范，输出也记录输入摘要。禁止在文档部署阶段从一个可变 latest URL 临时抓取 schema，否则相同文档提交可能在不同时间产生不同页面。

静态覆盖只能证明“写到了”

第一层门禁检查实现路由与规范 operation 的双向覆盖：公开 handler 未记录是 undocumented，实现不存在却仍公开是 ghost operation。比较时要识别框架前缀、可选尾斜线和版本路由，但不能用过度归一化把不同资源合并。内部健康检查可按策略排除，排除项有 owner 与理由。

每个 operation 继续检查参数位置、必填性、可空与缺失、媒体类型、认证方案、成功和错误状态、分页、幂等及弃用信息。生成页面必须保留这些内容，不能为了简洁隐藏 error response 或 scope。代码优先提取器若无法表达某项语义，应要求显式补充，而不是丢弃后继续发布。

结构变化通过兼容性门区分 additive、behavioral、deprecation 与 breaking。删除字段、收紧枚举、把 optional 改 required 容易识别；默认排序、权限、速率限制和错误优先级变化通常需要人工标注。REST API 版本控制负责版本政策，Agent API 契约兼容门负责消费者组合，reference 同步不能替代二者。

用已发布服务反证共同错误

第二层在隔离环境部署待发布服务制品，使用 canonical contract 生成请求，再由独立维护的 oracle 检查响应。至少覆盖一种成功、主要认证失败、代表性验证错误、未知字段、分页终点和声明的幂等行为。探针使用合成租户和可清理数据，写操作具有唯一场景 ID；不能对生产资源随意生成样例。

规范和实现若由同一个 AI 改成同样错误，schema validation 仍会绿色。因此 oracle 中的业务不变量来自已批准用户行为或兼容样本，并由另一所有权边界维护。例如创建后必须能按返回 ID 读回、重复幂等键不得产生第二条记录、无 scope 请求不得因为 UI 隐藏而成功。真实服务也不是自己的裁判。

HTTP 探针记录实际请求方法、目标版本、请求与响应摘要、状态和媒体类型。秘密、cookie 与个人数据在采集前移除；正文只保存合成字段或经过批准的摘要。失败要区分规范缺失、实现偏差、环境不可用和 oracle 未决，不能把后两者算作兼容。

这与开发者文档代码样例漂移门不同：后者证明公开片段在声明 SDK 组合中可复制执行，本篇证明 reference 的 operation 与部署服务同代。二者可共享 contract ID，却应保留独立失败信号。

让版本入口与制品一起提升

预览页明确显示待发布版本和提交，不占用稳定 URL。服务制品、canonical contract、reference 静态产物与探针收据组成一个发布集合；只有全部通过才把版本别名原子指向新集合。不能先更新 /docs/latest，再等待 API 部署，也不能让 API 回滚后文档仍解释新字段。

历史主版本保留不可变页面，并标出支持状态、终止日期和迁移入口。修正文案可以发布新的 docs revision，但若改变接口语义就必须生成新 contract generation。缓存键包含版本与摘要，CDN purge 后从多个位置验证页面标题、operation 数和示例摘要，避免边缘节点拼出新导航配旧正文。

人工验收关注机器难以判断的部分：摘要是否说明业务目的，错误是否给出安全恢复动作，权限 scope 是否容易误解，示例是否使用真实字段关系，弃用替代路径是否完整。AI 可以生成候选描述，但 owner 必须逐项接受新增或变化的用户承诺。

最终收据连接实现制品、规范摘要、文档摘要、探针结果、人工审阅人与发布时间，并进入编程 Agent 改动验证门。当任一摘要变化，旧收据失效。

API 文档同步不是“自动生成一次”的能力，而是让规范、实现、运行证据与用户入口共同移动。只有独立探针能反证、版本别名能回退、人工能解释语义时，Vibe Coding 才是在维护一个接口，而不是同时生成三份彼此赞同的猜测。