[67] OpenAPI Specification：把接口变成可执行契约

• 资料类型：规范
• 原始来源：https://spec.openapis.org/oas/latest.html
• 对应章节：第 3 章（PRD 与工程合同）、第 9 章（后端架构）、第 10 章（Agent：工具合同）

一句话

OpenAPI 的价值不只是生成文档，而是把接口的输入/输出/错误语义固定成可校验、可回归的契约。

你该从 OpenAPI 带走什么

• 契约优先：先把资源、错误码、幂等语义写清楚，再写实现。
• 可工具化：lint、破坏性变更检查、客户端生成，都可以变成门禁。
• 减少歧义：对 AI/Agent 来说，OpenAPI 就是工具说明书，越清晰越不容易乱调用。

在本书里怎么用

• 第 2 章把它当作文档即代码的核心产物：缺字段/不符合规范就阻断合并。
• 第 5/7 章把它作为工具调用的事实源：让工具接口可描述、可审计、可回滚。

常见误用

• 只写快乐路径，错误语义与边界条件缺失，最后实现各自为政。
• 契约与实现漂移：没有 lint/对比门禁，文档变成摆设。