OpenAPI Spec Generation
FreeEfficiently create and manage OpenAPI 3.1 specifications.
Free · Opens the source repo
What OpenAPI Spec Generation does
OpenAPI Spec Generation is a powerful tool designed for developers and API designers to generate, maintain, and validate OpenAPI 3.1 specifications. This skill is particularly useful when creating API documentation from scratch or generating specifications from existing codebases. It supports various design approaches, including design-first, code-first, and hybrid methods, allowing users to choose the best fit for their workflow. By leveraging this skill, teams can ensure that their API contracts remain compliant and well-documented throughout the development lifecycle.
The skill provides comprehensive patterns and best practices for structuring OpenAPI specifications, ensuring that users can produce high-quality documentation. It emphasizes the importance of reusability, clarity, and consistency in API design. Users can expect to find templates and detailed examples that cover a wide range of scenarios, making it easier to implement best practices effectively. The skill also assists in generating client SDKs from specifications, streamlining the integration process for developers.
In addition to documentation generation, OpenAPI Spec Generation facilitates the validation of API implementations against the defined specifications. This feature is crucial for maintaining the integrity of APIs as they evolve, ensuring that any changes made to the API are reflected in the documentation and that the API remains compliant with its contract. With this skill, teams can set up API documentation portals that enhance accessibility and usability for API consumers, further improving the overall developer experience.
Overall, OpenAPI Spec Generation is an essential tool for any team involved in API development, providing the necessary resources to create, maintain, and validate OpenAPI specifications efficiently.
When to use it
Use this skill when you need to create or update API documentation, generate specifications from code, or validate API implementations against defined contracts.
When not to use it
This skill may not be suitable for projects that do not require formal API documentation or for teams that prefer manual documentation processes without structured specifications.
What you can build with it
Creating API Documentation
Use this skill to generate comprehensive API documentation from scratch or existing codebases, ensuring clarity and compliance.
Validating API Implementations
Leverage the skill to validate that your API implementations meet the defined specifications, maintaining contract compliance.
Generating Client SDKs
Utilize the skill to generate client SDKs directly from your OpenAPI specifications, streamlining the development process for API consumers.
How to install OpenAPI Spec Generation
View source1. Install with the skills CLI
npx skills add wshobson/agents/openapi-spec-generation --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by wshobsonOpenAPI Spec Generation
Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.
When to Use This Skill
- 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
Core Concepts
1. OpenAPI 3.1 Structure
openapi: 3.1.0
info:
title: API Title
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/resources:
get: ...
components:
schemas: ...
securitySchemes: ...
2. Design Approaches
| Approach | Description | Best For |
|---|---|---|
| Design-First | Write spec before code | New APIs, contracts |
| Code-First | Generate spec from code | Existing APIs |
| Hybrid | Annotate code, generate spec | Evolving APIs |
Templates and detailed worked examples
Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.
Best Practices
Do's
- Use $ref - Reuse schemas, parameters, responses
- Add examples - Real-world values help consumers
- Document errors - All possible error codes
- Version your API - In URL or header
- Use semantic versioning - For spec changes
Don'ts
- Don't use generic descriptions - Be specific
- Don't skip security - Define all schemes
- Don't forget nullable - Be explicit about null
- Don't mix styles - Consistent naming throughout
- Don't hardcode URLs - Use server variables
Frequently asked questions about OpenAPI Spec Generation
Similar skills
Markdown to HTML Conversion
Efficiently convert Markdown documents to HTML.
Code Tour
Create structured walkthroughs for codebases.
Acquire Codebase Knowledge
Streamline onboarding with comprehensive codebase documentation.
Documentation & Modernization
Streamline codebase documentation and modernization planning.
Azure Resource Visualizer
Generate architecture diagrams for Azure resources.
CLAUDE.md Improver
Optimize your CLAUDE.md files for better project context.