api-designer

用途

API Designer 提供 REST 与 GraphQL API 架构方面的专业能力，重点覆盖 OpenAPI 3.1 规范、API 版本化策略、分页模式以及超媒体驱动设计（HATEOAS）。其目标是构建可扩展、文档完善、对开发者友好的 API，并统一错误处理与标准化。

主要能力

根据需求设计 RESTful 或 GraphQL API
创建用于 API 文档的 OpenAPI 3.1 规范
实现 API 版本化策略（URL、请求头、内容协商）
为大数据集设计分页、过滤与排序模式
构建符合 HATEOAS 的 API（超媒体驱动）
跨服务统一错误响应与状态码
设计 API 认证与授权模式

使用方式

该技能以工作流方式运作。以“设计带 OpenAPI 3.1 的 RESTful API”为例，流程包括：

资源建模：识别资源（如 Products、Categories、Reviews、Inventory），设计 URL 结构，例如：

GET    /v1/products              # List products (paginated)
POST   /v1/products              # Create product
GET    /v1/products/{id}         # Get product details
PUT    /v1/products/{id}         # Update product (full replacement)
PATCH  /v1/products/{id}         # Partial update
DELETE /v1/products/{id}         # Delete product

GET    /v1/products/{id}/reviews        # Get reviews for product
POST   /v1/products/{id}/reviews        # Create review
GET    /v1/products/{id}/reviews/{reviewId}  # Get specific review

GET    /v1/categories            # List categories
GET    /v1/categories/{id}       # Get category + subcategories

查询参数示例：

GET /v1/products?category=electronics&min_price=100&max_price=500&sort=price:asc&limit=20&cursor=abc123

编写 OpenAPI 3.1 规范（openapi.yaml），包含 info、servers、paths、components（schemas、responses、securitySchemes）等部分。规范中定义了分页响应结构（data、meta、links）、错误响应结构（error.code、error.message、error.details）以及安全方案（ApiKey、BearerAuth）。
生成文档，可使用 Redoc CLI 或 Swagger UI：

# Install Redoc CLI
npm install -g redoc-cli

# Generate static HTML documentation
redoc-cli bundle openapi.yaml -o api-docs.html

# Host documentation
npx serve api-docs.html

# Interactive Swagger UI
docker run -p 8080:8080 -e SWAGGER_JSON=/docs/openapi.yaml \
  -v $(pwd):/docs swaggerapi/swagger-ui

# Open http://localhost:8080 for interactive API testing

适用场景

从需求出发设计 RESTful 或 GraphQL API
为 API 文档创建 OpenAPI 3.1 规范
实现 API 版本化策略
为大数据集设计分页、过滤与排序
构建 HATEOAS 兼容 API
跨服务统一错误响应与状态码
设计 API 认证与授权模式

限制与不适用场景

以下情况不应调用该技能：

仅实现已设计好的 API 端点（应使用 backend-developer）
无 API 上下文的数据库模式设计（应使用 database-administrator）
前端 API 集成（应使用 frontend-developer）
API 安全实现（认证/授权应使用 security-engineer）
API 性能优化（应使用 performance-engineer）

反模式提示

资料中特别指出“不一致的错误响应”是常见反模式：不同端点返回不同结构的错误（如 {"error": "Invalid credentials"}、{"errors": [...]}、{"status": "error", "message": ..., "code": 500}），会导致客户端需要为每个端点编写自定义错误处理、前端开发者体验差、错误日志与监控困难。正确做法是统一错误响应结构，例如：

{
  "error": {
    "code": "invalid_credentials",
    "message": "The provided email or password is incorrect",
    "details": null,
    "request_id": "req_abc123"
  }
}

校验错误可包含多个字段：

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields failed validation",
    "details": {
      "fields": [
        { "field": "email", "message": "Invalid email format" },
        { "field": "password", "message": "Password must be at least 8 characters" }
      ]
    },
    "request_id": "req_def456"
  }
}

客户端可据此编写一致的错误处理逻辑。

集成模式

与 backend-developer：API Designer 创建规范，后端实现端点；协作错误响应格式与认证模式；工具包括 OpenAPI 代码生成、API 模拟。
与 frontend-developer：API 规范发布后前端消费；协作查询模式、分页、错误处理；工具包括从 OpenAPI/GraphQL schema 生成 TypeScript 类型。
与 security-engineer：API Designer 定义认证需求，安全工程师实现认证；协作限流、API 密钥管理、OAuth 流程；关键点包括 JWT 校验、API 网关安全策略。
与 devops-engineer：API 设计定稿后 DevOps 部署 API 网关；协作 API 版本化部署、蓝绿发布；工具包括 Kong、AWS API Gateway、Traefik 配置。