| name | openapi-spec-generation |
| description | This skill should be used when creating API documentation, generating SDKs, or ensuring API contract compliance. It generates and maintains OpenAPI 3.1 specifications. |
| allowed-tools | Read |
| metadata | {"triggers":"OpenAPI, Swagger, API specification, OpenAPI 3.1, API documentation, SDK generation, API contract","related-skills":"documentation-generation, java-spring-api, nestjs-api, python-dev","domain":"api-architecture","role":"specialist","scope":"design","output-format":"specification"} |
| last-reviewed | 2026-03-15 |
Iron Law: Never generate an OpenAPI spec without running it through a validator; always produce machine-parseable YAML/JSON, not prose descriptions.
OpenAPI Spec Generation
Generate, validate, and maintain OpenAPI 3.1 specifications for RESTful APIs. Supports design-first, code-first, and hybrid approaches across Java/Spring, Python/FastAPI, and TypeScript stacks.
When to Use
- Creating API documentation from scratch
- Generating OpenAPI specs from existing code
- Designing API contracts (design-first approach)
- Validating API implementations against specs
- Generating client SDKs from specs
- Setting up API documentation portals
Quick Start
Design-First:
- Copy the minimal skeleton from
reference/openapi-skeleton-template.md into openapi.yaml
- Add paths and schemas for the domain
- Validate:
spectral lint openapi.yaml
- Preview:
redocly preview-docs openapi.yaml
Code-First:
| Stack | Command |
|---|
| FastAPI | python -c "import json; from main import app; print(json.dumps(app.openapi(), indent=2))" > openapi.json |
| Spring Boot | curl http://localhost:8080/v3/api-docs > openapi.json |
| tsoa | npx tsoa spec |
Process Steps
Step 1: Choose Approach
| Approach | When to Use | Reference |
|---|
| Design-First | New APIs, contracts, external consumers | reference/openapi-skeleton-template.md |
| Code-First | Existing APIs, rapid iteration | reference/code-first-patterns.md |
| Hybrid | Evolving APIs, keep spec in sync | Both references above |
Step 2: Generate the Spec
Design-first -- Read reference/openapi-skeleton-template.md for the starter template. Copy the minimal skeleton, then customize paths, schemas, and security for the domain.
Code-first -- Read reference/code-first-patterns.md for annotated examples in:
- Java/Spring Boot (springdoc-openapi) -- annotations, config bean, DTOs
- Python/FastAPI -- Pydantic models, type hints, endpoint decorators
- TypeScript/tsoa -- decorators, interfaces, route controllers
Step 3: Add a Complete Example (if needed)
Read reference/complete-api-example.md for a full User Management API spec demonstrating all features: CRUD paths, pagination, filtering, error responses, rate limiting headers, security schemes, and reusable components.
Step 4: Validate and Lint
Read reference/validation-and-linting.md for:
- Spectral configuration (
.spectral.yaml)
- Redocly configuration
- Validation commands
- Custom linting rules (naming conventions, required fields)
Step 5a: Write the Developer Guide (if needed)
Read reference/developer-guide-patterns.md for:
- 9-section documentation structure (Introduction → Authentication → Quick Start → Endpoints → Data Models → Errors → Rate Limiting → Changelog → SDKs)
- Auth flow documentation template (obtain → use → refresh token)
- Multi-language code examples for all 3 backend stacks: Java/Spring Boot WebFlux (WebClient), Python/FastAPI (httpx async), TypeScript/NestJS (HttpService + fetch)
- Error handling reference (status codes, error response format, per-stack handling patterns)
- 4 common pitfalls with solutions (sync drift, missing errors, broken examples, unclear parameters)
Step 5b: Generate SDKs and Set Up CI/CD
Read reference/sdk-and-cicd.md for:
- SDK generation commands (TypeScript, Python, Java, Dart)
- GitHub Actions workflow for validation
- Full CI/CD pipeline (validate, generate, publish)
Reference Files
| File | Content | Size |
|---|
reference/openapi-skeleton-template.md | Minimal starter skeleton, structure overview, customization checklist | ~5KB |
reference/code-first-patterns.md | Java/Spring, Python/FastAPI, TypeScript/tsoa annotated examples | ~10KB |
reference/validation-and-linting.md | Spectral rules, Redocly config, validation commands, common mistakes and best practices | ~5KB |
reference/sdk-and-cicd.md | SDK generation commands, GitHub Actions workflows | ~5KB |
reference/complete-api-example.md | Full User Management API with all OpenAPI features | ~10KB |
reference/developer-guide-patterns.md | 9-section doc structure, auth flow template, multi-language code examples (Java WebFlux / Python FastAPI / TypeScript NestJS), error handling reference, 4 common pitfalls | ~8KB |
Resources
Error Handling
Schema validation failures: Run the spec through an OpenAPI validator before committing. Fix all $ref resolution errors first.
Breaking changes detected: When modifying existing endpoints, check for removed fields, changed types, or new required parameters. Document breaking changes in the spec description.
