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