Agent skill · writing content · erichowens
openapi-spec-writer
Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive
Why this skill is useful
Provides detailed domain-specific knowledge on OpenAPI specifications and tooling integration that the AI wouldn't reliably generate on its own.
What it needs
About 6k tokens when loaded. Last updated 2026-07-14. 180 stars on the source repository.
What this skill does
OpenAPI Spec Writer Overview Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract. When to Use Creating OpenAPI specifications for new APIs Documenting existing REST APIs Designing API contracts before implementation Generating client SDKs from specs Setting up interactive API documentation (Swagger UI, Redoc) Validating API responses against schemas Migrating from OpenAPI 2.0 (Swagger) to 3.x Capabilities Specification Writing OpenAPI 3.0 and 3.1 syntax Path and operation definitions Request/response schemas Authentication schemes Server configurations Schema Design JSON Schema with OpenAPI extensions Reusable component schemas Discriminators for polymorphism oneOf, anyOf, allOf composition Nullable types and defaults Documentation Quality Meaningful descriptions and examples Markdown in descriptions Request/response examples Error response documentation Deprecation notices Tooling Integration Swagger UI configuration Redoc customization Spectral linting rules SDK generation setup Mock server configuration Dependencies Works well with: api-architect - API design patterns rest-api-design - RESTful conventions typescript-pro - Generated client types github-actions-pipeline-builder - CI validation Examples Complete OpenAPI 3.1 Spec Polymorphic Schemas (Discriminator) Spectral Linting Rules Best Practices 1. Use components - Extract reusable schemas, parameters, responses 2. Provide examples - Real-world examples for every schema 3. Meaningful descriptions - Markdown-formatted, explain business context 4. Consistent naming - kebab-case paths, camelCase properties 5. Version your API - Include version in URL or header 6. Document errors - Define all error responses with examples 7. Use operationId - Unique, descriptive IDs for SDK generation 8. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills erichowens/openapi-spec-writer