openapi-spec-generation
Helps your agent create and update API documentation. Useful for ensuring docs are always correct and for generating client code.
What it does
This tool helps create and organize API documentation (interfaces that allow programs to talk to each other). It can generate this documentation from your code or from a prior design.
When to use it
- ✓When you need to document a new API.
- ✓When you want to generate documentation for an existing API in your code.
- ✓When you need to create a guide for other programs to use your API.
Example of what to ask your AI
“Create the OpenAPI documentation for this API that receives user data.”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
The tool analyzes your code or a design file to understand how your API works. Then, it generates a standardized file (OpenAPI 3.1) that describes all the details of your API.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add wshobson/agents --skill openapi-spec-generationOr download just the file:
curl -L https://raw.githubusercontent.com/wshobson/agents/main/plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
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
FAQ
What is OpenAPI?
It's a standard format for describing APIs, like a map that explains how to use an online service.
What's the difference between 'Design-First' and 'Code-First'?
'Design-First' is creating the map (documentation) before building the road (API). 'Code-First' is building the road and then generating the map from it.
Why use '$ref'?
It's like creating a shortcut to avoid repeating information. If you describe a data type in one place, you can use '$ref' to reuse that description elsewhere.
Details
Original description by the author
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.
repo: wshobson/agents
Popularity
- GitHub stars
- 41k
- Ranking position
- #4857
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
screen-reader-testing
Has your agent test websites using screen readers to ensure they are accessible.
wshobson/agents
wcag-audit-patterns
Helps your agent audit websites for accessibility and fix issues according to WCAG guidelines.
wshobson/agents
multi-reviewer-patterns
Enables your agent to coordinate parallel code reviews, deduplicating findings and consolidating reports.
wshobson/agents
parallel-debugging
Allows the agent to debug complex issues with parallel investigations and root cause analysis.
wshobson/agents
Similar skills
api-connector-builder
Has your agent build new API connections following the existing pattern. Use when you need to add one more integration without creating a new way of doing things.
affaan-m/ECC
api-design
Helps your agent design REST APIs following best practices. It's useful for defining how APIs communicate, how errors are shown, and how to organize data.
affaan-m/ECC
backend-patterns
Helps your agent with server-side architecture patterns and database optimization. It's useful for building or reviewing code that runs on the server.
affaan-m/ECC