OpenAPI 3.1 规范生成

要解决什么问题

REST 接口一旦在多个服务、前端与第三方之间流转，文档与实现漂移几乎是常态：路由改了、字段 nullable 了、错误码没写进契约，联调与 SDK 生成都会踩坑。OpenAPI 3.1 能把 HTTP 语义、Schema 与示例收敛成可机器读取的规范，但手写 YAML、从框架注解反推、以及「规范是否真覆盖线上行为」往往缺少统一做法。

技能如何工作

本技能围绕 OpenAPI 3.1 的创建、维护与校验，按你的目标先对齐约束与输入（现有代码、设计稿、或空白契约），再给出可执行步骤与验证方式，并对照常见最佳实践检查结果。

典型场景包括：

• 从零编写 API 文档与规范文件
• 从现有代码 抽取或生成 OpenAPI 描述
• 设计优先：先定契约再实现接口
• 实现校验：对照规范检查路由、参数、响应与错误模型
• 为 客户端 SDK 或 文档门户 提供规范作为单一事实来源

需要更完整的模式与示例时，可参照技能附带的 resources/implementation-playbook.md。

适用边界

任务与 OpenAPI 规范生成无关，或依赖本范围外的其他领域工具链时，不应强行套用本技能。它聚焦规范本身的生命周期，而不是替代你选定的框架、网关或 CI 产品的具体配置。