openapi-spec-generation
Automates creation, maintenance, and validation of OpenAPI 3.1 specifications for RESTful APIs.
Install
mkdir -p .claude/skills/openapi-spec-generation && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/448" && unzip -o skill.zip -d .claude/skills/openapi-spec-generation && rm skill.zipInstalls to .claude/skills/openapi-spec-generation
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.Key capabilities
- →Generate OpenAPI 3.1 specifications from code
- →Define API contracts using a design-first approach
- →Validate API implementations against specifications
- →Generate client SDKs from defined specs
- →Set up API documentation portals
How it works
The skill utilizes OpenAPI 3.1 structure to define API metadata, paths, and components. It supports design-first, code-first, or hybrid development workflows to maintain contract compliance.
Inputs & outputs
When to use openapi-spec-generation
- →Generating API docs from code
- →Defining a new API contract
- →Validating implementation against an OpenAPI spec
- →Generating client SDKs
About this skill
OpenAPI 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
When not to use it
- →When using generic descriptions
- →When skipping security scheme definitions
- →When mixing naming styles
Limitations
- →Requires explicit nullability definitions
- →Requires consistent naming conventions
- →Requires server variables instead of hardcoded URLs
How it compares
Unlike manual documentation, this approach automates the generation and validation of specifications directly from code or design patterns.
Compared to similar skills
openapi-spec-generation side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| openapi-spec-generation (this skill) | 22 | 2mo | No flags | Intermediate |
| microsoft-code-reference | 7 | 4mo | Review | Beginner |
| openai-knowledge | 5 | 4mo | No flags | Intermediate |
| agent-docs-api-openapi | 4 | 6mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by wshobson
View all by wshobson →You might also like
microsoft-code-reference
github
Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs.
openai-knowledge
openai
Use when working with the OpenAI API (Responses API) or OpenAI platform features (tools, streaming, Realtime API, auth, models, rate limits, MCP) and you need authoritative, up-to-date documentation (schemas, examples, limits, edge cases). Prefer the OpenAI Developer Documentation MCP server tools when available; otherwise guide the user to enable `openaiDeveloperDocs`.
agent-docs-api-openapi
ruvnet
Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi
openai-docs
openai
Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations (for example: Codex, Responses API, Chat Completions, Apps SDK, Agents SDK, Realtime, model capabilities or limits); prioritize OpenAI docs MCP tools and restrict any fallback browsing to official OpenAI domains.
http-generate
spring-ai-alibaba
Generates HTTP request examples for Spring Boot Web interfaces according to task specification and saves them as .http files in module-generate.md directories
paasta-api-endpoint
Yelp
Automates the creation of new PaaSTA API endpoints following established patterns