用途：本技能面向 OpenAPI 3.1（OAS 3.1）规范，用于设计 REST API、生成类型化客户端（TypeScript、Python、Go）、生成交互式文档、校验请求/响应载荷、契约优先开发及 API 网关配置。不适用于 GraphQL（用 GraphQL Schema）、gRPC（用 Protocol Buffers）、仅 WebSocket 协议，以及不跨网络边界的内部函数调用。OAS 3.1 是 JSON Schema Draft 2020-12 的严格超集，可完整兼容 JSON Schema 用于数据校验与类型生成。
主要能力：描述 HTTP API 的机器可读契约，覆盖端点、请求/响应 Schema、认证与错误格式。文档根包含 openapi、info、paths，openapi: '3.1.0' 为顶层必需。路径项用花括号表示路径参数，操作含 get、post、put、delete、patch，每个操作需要 operationId 与 responses。参数支持 in: path|query|header|cookie，路径参数始终为 required: true。请求体与响应按媒体类型（如 application/json）组织，每个操作至少一个响应。可用 $ref: '#/components/schemas/Name' 复用 Schema、参数与响应。Schema 类型含 string|number|integer|boolean|array|object，3.1 中数组支持 type: ["string", "null"]。组合用 oneOf、anyOf、allOf 建模多态与交叉类型，判别器用 discriminator.propertyName。安全方案经 securitySchemes 与顶层 security 定义，支持 Bearer、API key、OAuth2、OpenID Connect。标签用于文档分组。
代码生成与工具：openapi-typescript 可从规范生成零运行时 TypeScript 类型；openapi-fetch 基于生成类型提供类型安全 HTTP 客户端；openapi-react-query 生成类型安全的 React Query 钩子；zod-openapi 可从 Zod Schema 生成 OpenAPI 文档。文档工具提及 Swagger UI、Redoc 与 API 文档最佳实践。
常见错误与限制：3.1 中不应使用 nullable: true，改用 type: ["string", "null"]；操作须有唯一 operationId 以便代码生成；路径参数须为 required；避免到处内联 Schema，应抽取到 components/schemas 并用 $ref；allOf 的 required 数组合并而非冲突；oneOf/anyOf 中所有 Schema 须包含判别器属性；每个响应需有有意义描述；type: object 须定义 properties 或使用 additionalProperties；需打破循环 $ref 链；不可混用 3.0 与 3.1 语法。
协作：API 设计评审可委派 Task 智能体审计规范完整性与一致性；类型生成可委派 Explore 智能体查找项目特定 OpenAPI 工具配置；代码评审可委派 code-reviewer 智能体检查生成客户端用法。若 typescript-patterns 技能可用，可将高级 TypeScript 类型问题委派给它。其余细节资料暂未提供。