API契约生成Skill api-contract

---

名称: api-contract 描述: 根据需求生成OpenAPI、AsyncAPI或Protobuf契约。用于合同优先的API开发。 允许工具: 读取、全局搜索、grep、写入、技能、任务 参数提示: <api-description> [–format <openapi|asyncapi|protobuf>] [–version <x.y.z>]

/api-contract 命令

从需求或领域描述生成合同优先的API规范。

使用方式

/api-contract "用户注册，带有电子邮件验证"
/api-contract "下游系统的订单事件" format=asyncapi
/api-contract "高性能库存服务" format=protobuf

工作流程

步骤 1：分析需求

解析API描述以识别：

• 领域实体和资源
• 必需的操作（CRUD、查询、命令）
• 通信模式（同步REST、异步事件、RPC）
• 关键消费者和用例

步骤 2：选择契约格式

如果未指定格式，基于描述自动检测：

模式	推荐格式
“API”、“REST”、“端点”	OpenAPI 3.1
“事件”、“消息”、“流式传输”	AsyncAPI 3.0
“gRPC”、“高性能”、“内部”	Protocol Buffers

步骤 3：调用适当技能

加载相关技能：

• openapi-design 用于REST API
• asyncapi-design 用于事件驱动API
• protobuf-design 用于gRPC服务

步骤 4：设计资源模型

识别和结构化：

• 核心实体及其属性
• 值对象和枚举
• 实体之间的关系
• 请求/响应包装器

步骤 5：生成契约

创建API规范，包括：

• 完整的模式定义
• 所有操作/方法
• 身份验证配置
• 错误响应模式
• 每个操作的示例

步骤 6：输出结果

交付：

1. 契约规范（YAML或.proto）
2. 端点/通道/服务的摘要
3. 实现说明
4. 建议的测试场景

格式特定输出

OpenAPI 3.1

openapi: 3.1.0
info:
  title: 服务名称 API
  version: 1.0.0
paths:
  /resources:
    get: ...
    post: ...
components:
  schemas: ...
  securitySchemes: ...

AsyncAPI 3.0

asyncapi: 3.0.0
info:
  title: 服务事件
  version: 1.0.0
channels:
  resourceCreated:
    address: resources.created
    messages: ...
components:
  messages: ...
  schemas: ...

Protocol Buffers

syntax = "proto3";
package service.v1;

service ResourceService {
  rpc CreateResource(...) returns (...);
  rpc GetResource(...) returns (...);
}

message Resource {
  string id = 1;
  ...
}

示例

用户注册的REST API

/api-contract "用户注册API，带有电子邮件验证和密码重置"

输出：

• OpenAPI 3.1 规范
• POST /users（注册）
• POST /users/verify-email
• POST /users/forgot-password
• POST /users/reset-password
• JWT 身份验证方案

事件驱动的订单系统

/api-contract "用于履行和通知的订单生命周期事件" format=asyncapi

输出：

• AsyncAPI 3.0 规范
• 通道：orders.created, orders.submitted, orders.shipped
• CloudEvents 信封
• Kafka 绑定

gRPC 产品目录

/api-contract "带有搜索和库存的产品目录服务" format=protobuf

输出：

• Protocol Buffers 定义
• ProductService 带有CRUD + 搜索
• 批量操作的流式处理
• 时间戳的已知类型

集成

该命令与以下集成：

• requirements-elicitation：使用功能需求
• enterprise-architecture：与有界上下文对齐
• test-strategy：生成契约测试场景
• systems-design：遵循API设计模式