/api-specs-openapi

name: api-specs-openapi
description: OpenAPI 3.1 specification, schema design, code generation

OpenAPI Specification Patterns

> **Quick Guide:** Use OpenAPI 3.1 for API contracts. 3.1 is a superset of JSON Schema Draft 2020-12 -- use `type: ["string", "null"]` instead of `nullable: true`. Define all reusable schemas in `components/schemas` and reference with `$ref`. Always include `operationId` on every operation (it becomes the client method name). Use `openapi-typescript` to generate zero-runtime TypeScript types and `openapi-fetch` for a 6kb type-safe fetch client.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use OpenAPI 3.1 syntax -- `type: ["string", "null"]` NOT the 3.0 `nullable: true` keyword)**

**(You MUST define reusable schemas in `components/schemas` and reference with `$ref` -- NO inline schema duplication)**

**(You MUST include `operationId` on every path operation -- it becomes the generated client method name)**

**(You MUST use `openapi-typescript` for type generation and import types with `import type` -- types are zero-runtime)**

</critical_requirements>

---

**Auto-detection:** OpenAPI, openapi, swagger, openapi-typescript, openapi-fetch, createClient, paths, components, schemas, operationId, $ref, discriminator, oneOf, allOf, anyOf, openapi: "3.1", spec-first, API contract, API specification, code generation, schema design

**When to use:**

• Defining API contracts before or alongside implementation (spec-first or code-first)
• Generating TypeScript types from an existing OpenAPI spec
• Building type-safe API clients with automatic request/response validation
• Documenting REST APIs for external or internal consumers
• Designing reusable schema components with `$ref` composition

**When NOT to use:**

• Internal-only endpoints with no external consumers and no documentation needs
• GraphQL APIs (use GraphQL schema tooling instead)
• Simple scripts or prototypes where formal contracts add overhead

**Key patterns covered:**

• OpenAPI 3.1 spec structure (info, paths, components, servers)
• Schema design with JSON Schema Draft 2020-12 alignment
• `$ref` composition, `oneOf`/`allOf`/`anyOf`, discriminators
• Path operations with parameters, request bodies, and responses
• TypeScript type generation with `openapi-typescript` v7
• Type-safe fetch client with `openapi-fetch`
• Spec-first vs code-first decision framework

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Spec structure, schemas, paths, operations, `$ref` composition
• [examples/codegen.md](examples/codegen.md) - TypeScript type generation, `openapi-fetch` client
• [examples/validation.md](examples/validation.md) - Request/response validation, middleware patterns
• [reference.md](reference.md) - Decision frameworks, anti-patterns, quick-lookup tables

---

<philosophy>

Philosophy

**The spec IS the contract.** An OpenAPI document is the single source of truth for your API's shape. Types, documentation, client SDKs, and server validation are all derived from it -- never maintained separately.

**OpenAPI 3.1 aligns with JSON Schema Draft 2020-12.** This means any valid JSON Schema is a valid OpenAPI schema. Use `type` arrays for nullable (`["string", "null"]`), `if/then/else` for conditional schemas, and standard JSON Schema vocabulary.

**Spec-first (design-first) is recommended** for stable, multi-consumer APIs. Define the contract first, get feedback from consumers via mocks, then implement. Code-first works for rapid prototypes where the spec is generated from annotations.

**Use spec-first when:**

• Multiple teams consume the API
• API is public or has external consumers
• Contract stability matters (breaking changes are expensive)
• You want mocks and docs before writing any code

**Use code-first when:**

• Rapid prototyping where the spec is generated from code annotations
• Single-team internal APIs where the implementation IS the contract
• Framework provides first-class OpenAPI generation from code annotations

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Spec Structure

Every OpenAPI 3.1 document has four required top-level fields: `openapi`, `info`, `paths` (or `webhooks`), and implicitly `components` for reusable schemas.

openapi: "3.1.0"
info:
  title: Jobs API
  version: "1.0.0"
  description: Job listings and applications
servers:
  - url: https://api.example.com/v1
paths:
  /jobs:
    get:
      operationId: listJobs
      # ...
components:
  schemas:
    Job:
      # ...

**Why good:** `operationId` becomes the client method name, `servers` enables environment switching, schemas in `components` are reusable via `$ref`

See [examples/core.md](examples/core.md) for complete spec with paths, parameters, and responses.

---

Pattern 2: Schema Design with 3.1 Syntax

OpenAPI 3.1 uses JSON Schema Draft 2020-12. Key differences from 3.0: `nullable` is removed, use `type` arrays instead. `exclusiveMinimum`/`exclusiveMaximum` are numbers, not booleans.

# 3.1 nullable syntax
type: ["string", "null"]

# NOT 3.0 syntax:
# type: string
# nullable: true

components:
  schemas:
    Salary:
      type: object
      required: [min, max, currency]
      properties:
        min:
          type: integer
          minimum: 0
        max:
          type: integer
          minimum: 0
        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: ISO 4217 currency code

**Why good:** aligns with standard JSON Schema, tooling ecosystem understands it natively, `required` array is explicit

See [examples/core.md](examples/core.md) for enum, format, and composition examples.

---

Pattern 3: $ref Composition and Reuse

Define schemas once in `components/schemas`, reference everywhere with `$ref`. Use `allOf` to extend base schemas, `oneOf` for polymorphism with discriminators.

components:
  schemas:
    PaginatedResponse: