Openapi Spec Generation

This generates complete OpenAPI 3.1 specs from scratch or existing code, handling the tedious parts like parameter definitions, response schemas, and component references. You'd use it when documenting APIs, setting up contract-first development, or generating client SDKs. It covers the full spec structure including authentication schemes, error responses, and validation rules. The templates are comprehensive enough that you can copy-paste and modify rather than writing boilerplate YAML from memory. It's solid for both greenfield API design and retrofitting documentation onto existing endpoints.

skills.sh installs: 17K
GitHub stars: 42.4K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add wshobson/agents --skill openapi-spec-generation --agent claude-code

Installs into .claude/skills of the current project.

Files

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