Menu
契约生成技能，提供API契约文档的生成和管理能力
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
简洁风格技能，禁止废话，采用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