Menu
契约生成技能，提供API契约文档的生成和管理能力
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
简洁风格技能，禁止废话，采用caveman式简短直接的表达方式
个人文档管理技能，管理变更记录、方案设计Spec文档、测试报告等，统一存放在docs目录下
项目启动管理技能，支持Java Spring Boot和Vue项目的启动、重启、关闭操作，保持原有端口不变
方案调研技能，对方案设计、功能实现进行多方案比对分析，至少3个方案，建议5个左右的方案比对，包括业界标杆方案、大厂实现方案等
基于OpenAPI规范生成API文档，支持Swagger UI和ReDoc展示
提供后端单元测试指导和生成能力，支持JUnit 5、Mockito等框架
| name | common-contract-generation |
| description | 契约生成技能，提供API契约文档的生成和管理能力 |
| trigger | 需要定义API接口契约时 |
| disable-when | 项目已有完善的API契约或使用其他契约工具 |
| category | backend |
| tags | ["api","contract","swagger","openapi"] |
提供 API 契约文档的生成和管理能力，帮助团队定义和维护服务间的接口契约，确保前后端协作的一致性。
在以下情况调用此技能：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| apiName | String | 是 | API 名称 |
| endpoints | List<Endpoint> | 是 | 接口端点列表 |
| format | String | 否 | 输出格式（openapi3/swagger2） |
| version | String | 否 | API 版本 |
{
"status": "SUCCESS",
"apiName": "用户服务 API",
"version": "1.0.0",
"openapiSpec": "OpenAPI YAML/JSON 规范",
"endpoints": [
{
"path": "/api/users",
"method": "GET",
"summary": "获取用户列表",
"request": {},
"response": {}
}
],
"validationResult": {
"valid": true,
"errors": []
},
"generatedFiles": ["openapi.yaml", "client-sdk.ts"]
}
需求分析 → 接口设计 → 契约编写 → 契约验证 → 文档生成 → SDK生成 → Mock生成
| 检查项 | 说明 | 状态 |
|---|---|---|
| 路径规范 | API 路径是否符合 REST 规范 | ✅/❌ |
| HTTP方法 | 是否使用正确的 HTTP 方法 | ✅/❌ |
| 参数完整 | 请求参数是否完整定义 | ✅/❌ |
| 响应定义 | 响应结构是否完整定义 | ✅/❌ |
| 错误处理 | 是否定义错误响应 | ✅/❌ |
| 状态码 | HTTP 状态码是否正确使用 | ✅/❌ |
| 版本管理 | 是否有版本控制策略 | ✅/❌ |
| 文档完整 | 是否有必要的描述和示例 | ✅/❌ |
openapi: 3.0.3
info:
title: 用户服务 API
description: 用户管理相关接口
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: 获取用户列表
description: 获取所有用户的列表
parameters:
- name: page
in: query
description: 页码
required: false
schema:
type: integer
default: 1
responses:
'200':
description: 成功获取用户列表
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
required:
- id
- email
/api/user-profilescomponents:
schemas:
ErrorResponse:
type: object
properties:
code:
type: string
description: 错误代码
message:
type: string
description: 错误消息
details:
type: array
items:
type: string
description: 详细错误信息
required:
- code
- message
| 策略 | 说明 | 适用场景 |
|---|---|---|
| URL 版本 | /v1/users | 简单直接，便于调试 |
| Header 版本 | Accept-Version: 1.0 | 保持 URL 简洁 |
| Media Type 版本 | Accept: application/vnd.example.v1+json | 符合 REST 最佳实践 |
| 组件 | 职责 | 描述 |
|---|---|---|
| ContractDesigner | 契约设计器 | 设计 API 接口契约 |
| SpecGenerator | 规范生成器 | 生成 OpenAPI 规范 |
| ContractValidator | 契约验证器 | 验证契约一致性 |
| SdkGenerator | SDK 生成器 | 生成客户端 SDK |
| MockGenerator | Mock 生成器 | 生成 Mock 数据 |
| 变量名 | 说明 | 默认值 |
|---|---|---|
| CONTRACT_FORMAT | 默认输出格式 | openapi3 |
| API_VERSION | 默认 API 版本 | 1.0.0 |
contract:
format: openapi3
version: 1.0.0
output:
spec: openapi.yaml
docs: docs/api
sdk:
- language: typescript
output: src/client
- language: java
output: client/java