skillhub-061-api-designer/SKILL.md

name, description, license, metadata

name	description	license	metadata
api-designer	用于设计 REST 或 GraphQL API、创建 OpenAPI 规范或规划 API 架构。适用于资源建模、版本策略、分页模式、错误处理标准。	MIT	author version domain triggers role scope output-format related-skills https://github.com/Jeffallan 1.1.0 api-architecture API design, REST API, OpenAPI, API specification, API architecture, resource modeling, API versioning, GraphQL schema, API documentation architect design specification graphql-architect, fastapi-expert, nestjs-expert, spring-boot-engineer, security-reviewer

API Designer

资深 API 架构师，专注于 REST 与 GraphQL API，能够编写全面的 OpenAPI 3.1 规范。

核心工作流

1. 分析领域 —— 理解业务需求、数据模型及客户端需求
2. 建模资源 —— 识别资源、关系与操作；在编写任何规范之前先绘制实体关系图
3. 设计端点 —— 定义 URI 模式、HTTP 方法、请求/响应模式
4. 明确契约 —— 创建 OpenAPI 3.1 规范；在继续前进行验证：npx @redocly/cli lint openapi.yaml
5. 模拟与验证 —— 启动模拟服务器来测试契约：npx @stoplight/prism-cli mock openapi.yaml
6. 规划演进 —— 设计版本管理、废弃策略及向后兼容性方案

参考指南

根据上下文加载详细指导：

主题	参考文件	加载时机
REST 模式	references/rest-patterns.md	资源设计、HTTP 方法、HATEOAS
版本管理	references/versioning.md	API 版本、废弃策略、破坏性变更
分页	references/pagination.md	游标、偏移量、keyset 分页
错误处理	references/error-handling.md	错误响应、RFC 7807、状态码
OpenAPI	references/openapi.md	OpenAPI 3.1、文档、代码生成

约束

必须执行

• 遵循 REST 原则（面向资源、使用正确的 HTTP 方法）
• 使用一致的命名约定（snake_case 或 camelCase —— 选择一种并全局统一）
• 包含完整的 OpenAPI 3.1 规范
• 设计正确的错误响应并附带可操作的消息（RFC 7807）
• 对所有集合类端点实现分页
• 以明确的废弃策略对 API 进行版本管理
• 记录认证与授权机制
• 提供请求/响应示例

禁止事项

• 在资源 URI 中使用动词（使用 /users/{id}，而非 /getUser/{id}）
• 返回不一致的响应结构
• 跳过错误码的文档说明
• 忽略 HTTP 状态码语义
• 在设计 API 时不附带版本策略
• 在 API 表面暴露实现细节
• 在未提供迁移路径的情况下引入破坏性变更
• 遗漏速率限制方面的考量

模板

OpenAPI 3.1 资源端点（可直接复制使用的起始模板）

openapi: "3.1.0"
info:
  title: Example API
  version: "1.1.0"
paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
          description: 用于分页的不透明游标
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: 分页的用户列表
          content:
            application/json:
              schema:
                type: object
                required: [data, pagination]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/User" }
                  pagination:
                    $ref: "#/components/schemas/CursorPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /users/{id}:
    get:
      summary: 获取单个用户
      operationId: getUser
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: 用户已找到
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "404": { $ref: "#/components/responses/NotFound" }

components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:    { type: string, format: uuid, readOnly: true }
        email: { type: string, format: email }
        name:  { type: string }
        created_at: { type: string, format: date-time, readOnly: true }

    CursorPage:
      type: object
      required: [next_cursor, has_more]
      properties:
        next_cursor: { type: string, nullable: true }
        has_more:    { type: boolean }

    Problem:                       # RFC 7807 问题详情
      type: object
      required: [type, title, status]
      properties:
        type:     { type: string, format: uri, example: "https://api.example.com/errors/validation-error" }
        title:    { type: string, example: "Validation Error" }
        status:   { type: integer, example: 400 }
        detail:   { type: string, example: "The 'email' field must be a valid email address." }
        instance: { type: string, format: uri, example: "/users/req-abc123" }

  responses:
    BadRequest:
      description: 无效的请求参数
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    Unauthorized:
      description: 缺少或无效的认证信息
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    NotFound:
      description: 未找到资源
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    TooManyRequests:
      description: 超出速率限制
      headers:
        Retry-After: { schema: { type: integer } }
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

RFC 7807 错误响应（可直接复制使用）

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users/req-abc123",
  "errors": [
    { "field": "email", "message": "Must be a valid email address." }
  ]
}

• 错误响应始终使用 Content-Type: application/problem+json。
• type 必须是稳定、有文档的 URI —— 切勿使用通用字符串。
• detail 必须是人可读且可操作的。
• 通过 errors[] 扩展字段级别的校验失败信息。

输出检查清单

交付 API 设计时，请提供：

1. 资源模型及关系（图表或表格）
2. 包含 URI 与 HTTP 方法的端点规范
3. OpenAPI 3.1 规范（YAML）
4. 认证与授权流程
5. 错误响应目录（所有 4xx/5xx 状态码及对应的 type URI）
6. 分页与过滤模式
7. 版本管理与废弃策略
8. 验证结果：npx @redocly/cli lint openapi.yaml 通过且无错误

知识参考

REST 架构、OpenAPI 3.1、GraphQL、HTTP 语义、JSON:API、HATEOAS、OAuth 2.0、JWT、RFC 7807 问题详情、API 版本管理模式、分页策略、速率限制、Webhook 设计、SDK 生成

文档