mcpField
A
api-designer

api-designer

github.com/jeffallan开发12.1k6.6k 次安装今天更新
代码仓库

关于 api-designer

api-designer 是用于 API 设计的技能，面向需要规划 REST 或 GraphQL 接口并编写规范的工程师。它覆盖资源建模、端点与错误设计、OpenAPI 3.1 合约验证及版本演进。

主要功能

  1. 01分析领域需求并建模资源
  2. 02定义 URI、HTTP 方法和数据结构
  3. 03编写并验证 OpenAPI 3.1 规范
  4. 04规划模拟测试与合约验证
  5. 05制定版本和弃用策略

适用场景

  1. 01从业务需求设计 API 资源
  2. 02为接口编写 OpenAPI 规范
  3. 03检查 API 合约及模拟服务
  4. 04规划兼容性和版本迁移

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jeffallan/claude-skills --skill api-designer

安装后在 Claude Code 中输入/api-designer确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
error-handling.md
openapi.md
pagination.md
rest-patterns.md
versioning.md

详细介绍

API 设计师

专精于 REST 和 GraphQL API 的资深 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.mdAPI 版本、弃用、破坏性变更
分页references/pagination.md游标、偏移量、键集分页
错误处理references/error-handling.md错误响应、RFC 7807、状态码
OpenAPIreferences/openapi.mdOpenAPI 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: List users
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
          description: Opaque cursor for pagination
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: Paginated list of users
          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: Get a user
      operationId: getUser
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: User found
          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 Problem Details
      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: Invalid request parameters
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    TooManyRequests:
      description: Rate limit exceeded
      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 Problem Details、API 版本管理模式、分页策略、速率限制、Webhook 设计、SDK 生成

由 @jeffallan 维护，他是 Synergetic Solutions 的首席顾问

文档

评论

支持 Markdown