openapi-spec-generation

Use it when:: You're documenting a REST API, designing its contract before writing code, or need a spec to generate client SDKs from.
It does:: Picks design-first, code-first or hybrid to suit the API, and writes the spec with shared schemas, examples, every error and security schemes.
You get:: An OpenAPI 3.1 YAML spec; a separate file has a complete one for a user-management API to start from.

TL;DR

A reference for OpenAPI 3.1, the standard format for describing REST APIs. Writing the spec before the code suits new APIs and contracts, generating it from code suits existing APIs, and annotating code to generate it suits APIs that keep changing. Its rules: reuse schemas, parameters and responses with $ref, add realistic examples, document every error code, version the API in the URL or a header and the spec with semantic versioning, define every security scheme, state nullability explicitly, keep naming consistent and use server variables instead of hardcoded URLs. The separate file's spec has list, create, read, update and delete endpoints with pagination, schemas for users, requests, paginated lists and errors, shared parameters, standard responses for bad requests, missing auth, not found and rate limits, and bearer-token and API-key security. That file points to a third with code-first templates for FastAPI and for TypeScript with tsoa, linting with Spectral and Redocly, and generating TypeScript, Python and Go clients with OpenAPI Generator.

Summarizes the skill at 4bde316.

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

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 17,000 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Jan 20, 2026 on skills.sh

Weekly Downloads

210

-14% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	244
Sep 28	255
Oct 5	339
Oct 12	286
Oct 19	267
Oct 26	316
Nov 2	292
Nov 9	210

Category	category:engineering category:writing category:software-engineering Test-first work, implementation from specs, git hygiene and scope control. Articles, docs, internal comms, research write-ups and prose that doesn't read as generated. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:guidelines Knowledge and rules the agent applies while it works: best practices, design principles, API references.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	docs-writing backend
Stack	stack:openapi

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

name: openapi-spec-generation
description: 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.

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