openapi-spec-generation

Overview

What is openapi-spec-generation?

openapi-spec-generation is a practical skill for developers and API teams who need to generate, maintain, and validate OpenAPI 3.1 specifications for RESTful APIs. It supports both code-first and design-first workflows, making it suitable for new API projects, existing codebases, and evolving API contracts. This skill helps you create accurate API documentation, validate implementations, and generate client SDKs from your OpenAPI specs.

Who Should Use This Skill?

• API developers and architects designing new RESTful APIs
• Teams maintaining or documenting existing APIs
• Anyone needing to ensure API contract compliance or automate SDK/documentation generation

Problems It Solves

• Streamlines the creation of OpenAPI 3.1 specs from code or design documents
• Simplifies API documentation and contract validation
• Enables automated client SDK generation and API portal setup

How to Use

Installation Steps

1. Add the Skill:
   Install openapi-spec-generation using the following command:

   npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation
   

2. Explore Key Files:

   • Start with SKILL.md for an overview and usage patterns.
   • Review references/code-first-and-tooling.md for code-first generation examples (e.g., using Python/FastAPI or TypeScript/tsoa).
   • Check the references/ folder for advanced patterns and templates.

3. Adapt to Your Workflow:

   • Use the design-first approach to write specs before coding, ideal for new APIs or strict contract-first development.
   • Use the code-first approach to generate specs from annotated code, suitable for existing APIs or rapid prototyping.
   • Combine both approaches for hybrid workflows as your API evolves.

Example Use Cases

• Design-First: Draft your OpenAPI 3.1 spec in YAML, then implement the API to match.
• Code-First: Use frameworks like FastAPI (Python) to auto-generate OpenAPI specs from code annotations.
• Validation: Ensure your API implementation matches the OpenAPI contract for reliable integrations.
• SDK Generation: Use the spec to generate client libraries for multiple languages.

FAQ

What does openapi-spec-generation actually do?

openapi-spec-generation provides patterns and templates for generating and maintaining OpenAPI 3.1 specs, supporting both code-first and design-first approaches. It helps automate documentation, validation, and SDK generation for RESTful APIs.

How do I get started after installing?

Begin by reading SKILL.md for a high-level overview. For code-first workflows, see references/code-first-and-tooling.md for practical examples using frameworks like FastAPI. Adapt the templates and patterns to fit your project's needs.

Is this skill suitable for non-REST APIs?

openapi-spec-generation is focused on RESTful APIs and OpenAPI 3.1. For other API paradigms (e.g., GraphQL), this skill may not be a direct fit.

Can I use this for both new and existing APIs?

Yes. The skill supports design-first (new APIs) and code-first (existing APIs) workflows, as well as hybrid approaches.

Where can I find more examples or templates?

Check the references/ folder, especially references/code-first-and-tooling.md, for advanced usage patterns and sample code.

How do I validate my API against the spec?

While this skill provides patterns and templates, you can use standard OpenAPI tools (like Swagger, Redoc, or openapi-generator) alongside these patterns for validation and SDK generation.

Open the Files tab to browse the full file tree, including nested references and helper scripts for deeper integration.