Writing OpenAPI Specs

Reference for OpenAPI best practices and conventions. This skill provides guidance on taste, conventions, and grey areas not covered by the OpenAPI specification itself.

When to Use This Skill

• Writing a new OpenAPI specification
• Improving operation naming and organization
• Expressing complex data types (enums, polymorphism, nullable)
• Handling file uploads, streaming, or server-sent events
• Making specs more code-gen friendly
• Understanding reusability patterns (components vs inline)

Core Principles

Naming Conventions

Operation IDs: Use lowercase with underscores, following resource_action pattern: