openapi-spec-generation

SKILL.md

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