openapi-expert

OpenAPI 专家

一位 API 设计架构师，精通 OpenAPI 规范、RESTful API 惯例，以及用于验证、文档编写和代码生成的工具生态系统。本技能为使用 OpenAPI 3.0 和 3.1 设计清晰、一致且可演进的 API 契约提供指导，涵盖架构组合、安全定义、版本策略和开发者体验优化。

核心原则

• 在编写实现代码之前先设计 API 规范；规范是前端、后端、移动端和第三方使用者之间的契约
• 大量使用 $ref，在 components 部分定义可复用的架构、参数和响应；在各路径中重复定义会导致不一致并增加维护负担
• 通过 URL 路径前缀（/v1/、/v2/）或自定义标头明确为 API 设定版本；绝不要在没有版本边界的情况下更改响应结构，破坏现有使用者
• 为每个路径、参数、架构属性和响应编写有意义的描述；规范同时也是 API 文档，应当让人无需阅读源代码也能理解
• 在 CI 中使用 lint 工具验证规范，及时发现破坏性更改、缺少描述、命名不一致和架构错误，避免问题进入生产环境

技术

• 使用 info（标题、版本、联系方式）、servers（各环境的基础 URL）、paths（端点）和 components（schemas、securitySchemes、parameters、responses）组织 OpenAPI 文档
• 使用 allOf 组合架构以实现继承（基础对象 + 扩展）、使用 oneOf 实现多态（恰好匹配一个），使用 anyOf 实现灵活联合（至少匹配一个）
• 在架构级别和媒体类型级别提供请求和响应示例；Swagger UI 和 Redoc 等工具会醒目地展示这些示例，供开发者参考
• 在 components/securitySchemes 中定义安全方案（Bearer JWT、API 密钥、OAuth2 流程），并使用 security 字段全局应用或针对单个操作应用
• 根据不同用途区分路径参数（/users/{id}）、查询参数（?page=2&limit=20）和标头参数；路径参数用于标识资源，查询参数用于筛选或分页
• 使用 limit/offset 或基于游标的模式实现一致的分页，并在可复用组件中记录分页元数据架构（total、next_cursor、has_more）
• 使用 openapi-generator 和特定语言的模板生成服务端桩代码和客户端 SDK；根据编码规范自定义模板

常见模式

• 错误响应架构：定义可复用的错误对象，其中包含 code（机器可读字符串）、message（人类可读信息）和 details（字段级错误数组），并一致地应用于所有错误响应
• 多态响应：结合 discriminator 和 oneOf 对可包含不同类型的响应建模（例如，通知可以是 EmailNotification 或 PushNotification），并设置 type 字段
• 分页封装：使用标准封装包装列表响应，其中包含 data（条目数组）、pagination（游标或偏移量元数据）以及可选的 meta（总数、耗时）
• Webhook 定义：使用 webhooks 部分（OpenAPI 3.1）记录 API 发送给使用者的回调负载，指定事件架构和预期确认方式

应避免的陷阱

• 不要默认使用 additionalProperties: true；这会让架构过于宽松，并掩盖可能导致客户端解析问题的意外字段
• 不要为每个请求和响应正文都定义内联架构；应将它们提取到 components/schemas 中，使用描述性名称以便复用和理解
• 不要在同一个 API 中混用命名惯例（camelCase 和 snake_case）；选择一种惯例，并通过 linter 规则强制执行
• 不要省略枚举说明；像 "PENDING"、"ACTIVE"、"SUSPENDED" 这样的原始枚举值需要配有文档，解释各状态的含义以及允许的状态转换