openapi-spec-generation

# 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 ```yaml 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