菜单
Use when converting API contracts to OpenAPI 3.1 specification or generating SDK clients.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | openapi-spec-generation |
| description | Use when converting API contracts to OpenAPI 3.1 specification or generating SDK clients. |
| allowed-tools | Read, Write, Bash |
This skill guides the creation of OpenAPI 3.1 specifications from the API contracts defined in Phase 3, enabling SDK generation and interactive documentation.
See references/openapi-template.yaml for the complete OpenAPI 3.1 specification template. The template includes info block with metadata and rate limits, multiple server environments, tagged endpoints with operationIds, reusable parameters and schemas in components section, security schemes (Bearer JWT), request/response schemas, and standardized error responses.
From api-contracts.md:
### GET /users
**Response 200:**
```json
{ "data": [...], "meta": {...} }
To OpenAPI:
```yaml
paths:
/users:
get:
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
From response examples, create component schemas.
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
| Issue | Fix |
|---|---|
| Missing operationId | Add unique operationId to each operation |
| No examples | Add example values to schemas |
| Missing descriptions | Document all endpoints and schemas |
# TypeScript SDK
openapi-generator generate \
-i openapi.yaml \
-g typescript-fetch \
-o ./sdk/typescript
# Python SDK
openapi-generator generate \
-i openapi.yaml \
-g python \
-o ./sdk/python
npm install orval
orval --config orval.config.ts
During Phase 3:
03-api-planning/openapi.yamlEnhanced planning system combining UltraPlan's 6-phase pipeline with Clear Thought's 11 structured thinking frameworks. Takes a plain-English idea and produces a complete, AI-executable implementation plan with rigorous thinking at every phase.
Use when defining API endpoints, designing request/response schemas, or establishing API contracts during framework planning.
Use when documenting architectural decisions, comparing technology options, or recording rationale for framework choices.
Use when selecting architecture patterns (MVC, hexagonal, clean, microservices) for a new project.
Use when creating or updating blueprint files in .framework-blueprints/ directory.
Use when designing CI/CD pipelines or creating GitHub Actions / GitLab CI configuration.