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.
1---2name: openapi-spec-generation3description: This skill should be used when creating API documentation, generating SDKs, or ensuring API contract compliance. It generates and maintains OpenAPI 3.1 specifications.4---56**Iron Law:** Never generate an OpenAPI spec without running it through a validator; always produce machine-parseable YAML/JSON, not prose descriptions.78# OpenAPI Spec Generation910Generate, 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.1112## When to Use1314- Creating API documentation from scratch15- Generating OpenAPI specs from existing code16- Designing API contracts (design-first approach)17- Validating API implementations against specs18- Generating client SDKs from specs19- Setting up API documentation portals2021## Quick Start2223**Design-First:**241. Copy the minimal skeleton from `reference/openapi-skeleton-template.md` into `openapi.yaml`252. Add paths and schemas for the domain263. Validate: `spectral lint openapi.yaml`274. Preview: `redocly preview-docs openapi.yaml`2829**Code-First:**3031| Stack | Command |32|-------|---------|33| FastAPI | `python -c "import json; from main import app; print(json.dumps(app.openapi(), indent=2))" > openapi.json` |34| Spring Boot | `curl http://localhost:8080/v3/api-docs > openapi.json` |35| tsoa | `npx tsoa spec` |3637## Process Steps3839### Step 1: Choose Approach4041| Approach | When to Use | Reference |42|----------|-------------|-----------|43| **Design-First** | New APIs, contracts, external consumers | `reference/openapi-skeleton-template.md` |44| **Code-First** | Existing APIs, rapid iteration | `reference/code-first-patterns.md` |45| **Hybrid** | Evolving APIs, keep spec in sync | Both references above |4647### Step 2: Generate the Spec4849**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.5051**Code-first** -- Read `reference/code-first-patterns.md` for annotated examples in:52- Java/Spring Boot (springdoc-openapi) -- annotations, config bean, DTOs53- Python/FastAPI -- Pydantic models, type hints, endpoint decorators54- TypeScript/tsoa -- decorators, interfaces, route controllers5556### Step 3: Add a Complete Example (if needed)5758Read `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.5960### Step 4: Validate and Lint6162Read `reference/validation-and-linting.md` for:63- Spectral configuration (`.spectral.yaml`)64- Redocly configuration65- Validation commands66- Custom linting rules (naming conventions, required fields)6768### Step 5a: Write the Developer Guide (if needed)6970Read `reference/developer-guide-patterns.md` for:71- 9-section documentation structure (Introduction → Authentication → Quick Start → Endpoints → Data Models → Errors → Rate Limiting → Changelog → SDKs)72- Auth flow documentation template (obtain → use → refresh token)73- Multi-language code examples for all 3 backend stacks: Java/Spring Boot WebFlux (WebClient), Python/FastAPI (httpx async), TypeScript/NestJS (HttpService + fetch)74- Error handling reference (status codes, error response format, per-stack handling patterns)75- 4 common pitfalls with solutions (sync drift, missing errors, broken examples, unclear parameters)7677### Step 5b: Generate SDKs and Set Up CI/CD7879Read `reference/sdk-and-cicd.md` for:80- SDK generation commands (TypeScript, Python, Java, Dart)81- GitHub Actions workflow for validation82- Full CI/CD pipeline (validate, generate, publish)8384## Reference Files8586| File | Content | Size |87|------|---------|------|88| `reference/openapi-skeleton-template.md` | Minimal starter skeleton, structure overview, customization checklist | ~5KB |89| `reference/code-first-patterns.md` | Java/Spring, Python/FastAPI, TypeScript/tsoa annotated examples | ~10KB |90| `reference/validation-and-linting.md` | Spectral rules, Redocly config, validation commands, common mistakes and best practices | ~5KB |91| `reference/sdk-and-cicd.md` | SDK generation commands, GitHub Actions workflows | ~5KB |92| `reference/complete-api-example.md` | Full User Management API with all OpenAPI features | ~10KB |93| `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 |9495## Resources9697- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)98- [Swagger Editor](https://editor.swagger.io/)99- [Redocly](https://redocly.com/)100- [Spectral](https://stoplight.io/open-source/spectral)101- [OpenAPI Generator](https://openapi-generator.tech/)102- [springdoc-openapi](https://springdoc.org/)103104## Error Handling105106**Schema validation failures**: Run the spec through an OpenAPI validator before committing. Fix all `$ref` resolution errors first.107108**Breaking changes detected**: When modifying existing endpoints, check for removed fields, changed types, or new required parameters. Document breaking changes in the spec description.
kumaran-is