# TypeScript Code Generation

> Related: [core.md](core.md) for spec structure, [validation.md](validation.md) for request/response validation

---

## Pattern 1: CLI Type Generation with openapi-typescript

Generate zero-runtime TypeScript types from your OpenAPI spec.

### Basic Usage

```bash
# From local file
npx openapi-typescript ./api/openapi.yaml -o ./api/schema.d.ts

# From remote URL
npx openapi-typescript https://api.example.com/openapi.json -o ./api/schema.d.ts

# With useful flags
npx openapi-typescript ./api/openapi.yaml -o ./api/schema.d.ts \
  --immutable \           # Generate readonly properties and arrays
  --alphabetize \         # Sort types alphabetically
  --export-type           # Use 'type' instead of 'interface'
```

### Useful CLI Flags

| Flag                     | Default | Purpose                                      |
| ------------------------ | ------- | -------------------------------------------- |
| `--immutable`            | `false` | Generate `readonly` properties and arrays    |
| `--alphabetize`          | `false` | Sort generated types alphabetically          |
| `--export-type`          | `false` | Export `type` instead of `interface`         |
| `--enum`                 | `false` | Generate TypeScript enums (vs string unions) |
| `--default-non-nullable` | `true`  | Properties with defaults are non-nullable    |
| `--path-params-as-types` | `false` | Enable dynamic string lookups on paths       |
| `--exclude-deprecated`   | `false` | Omit deprecated fields                       |
| `--check`                | `false` | Verify types match current schema (CI)       |

---

## Pattern 2: Multi-Schema Config with redocly.yaml

For projects with multiple OpenAPI specs, use `redocly.yaml` (globbing is deprecated in v7).

```yaml
# redocly.yaml
apis:
  jobs@v1:
    root: ./specs/jobs.yaml
    x-openapi-ts:
      output: ./generated/jobs.ts
  companies@v1:
    root: ./specs/companies.yaml
    x-openapi-ts:
      output: ./generated/companies.ts
      # Per-schema overrides
      alphabetize: true
      immutable: true
```

```bash
# Generate all schemas (reads redocly.yaml automatically)
npx openapi-typescript
```

### Authenticated Remote Specs

```yaml
# redocly.yaml
resolve:
  http:
    headers:
      - matches: https://api.example.com/**
        name: X-API-KEY
        envVariable: API_KEY
```

---

## Pattern 3: Using Generated Types

The generated file exports `paths`, `components`, `operations`, and other top-level types.

```typescript
import type { paths, components } from "./api/schema.d.ts";

// Access schema types directly
type Job = components["schemas"]["Job"];
type Error = components["schemas"]["Error"];
type CreateJobInput = components["schemas"]["CreateJobInput"];

// Access path operation types
type ListJobsQuery = paths["/jobs"]["get"]["parameters"]["query"];

type ListJobsResponse =
  paths["/jobs"]["get"]["responses"]["200"]["content"]["application/json"];

type GetJobResponse =
  paths["/jobs/{jobId}"]["get"]["responses"]["200"]["content"]["application/json"];
```

**Why good:** all types derive from the spec, changing the spec and regenerating keeps everything in sync, zero runtime cost

---

## Pattern 4: openapi-fetch Client Setup

`openapi-fetch` is a 6kb type-safe fetch wrapper. It infers all types from the generated `paths` type.

### Basic Client

```typescript
import createClient from "openapi-fetch";
import type { paths } from "./api/schema.d.ts";

const API_BASE_URL = "https://api.example.com/v1";

export const apiClient = createClient<paths>({
  baseUrl: API_BASE_URL,
});
```

### CRUD Operations

```typescript
// GET -- list with query params
const { data: jobList, error: listError } = await apiClient.GET("/jobs", {
  params: {
    query: { page: 1, limit: 20, status: "active" },
  },
});

// GET -- single resource with path param
const { data: job, error: getError } = await apiClient.GET("/jobs/{jobId}", {
  params: { path: { jobId: "abc-123" } },
});

// POST -- create with request body
const { data: newJob, error: createError } = await apiClient.POST("/jobs", {
  body: {
    title: "Senior Engineer",
    companyId: "company-456",
    salary: { min: 120000, max: 180000, currency: "USD" },
  },
});

// PUT -- update
const { data: updated, error: updateError } = await apiClient.PUT(
  "/jobs/{jobId}",
  {
    params: { path: { jobId: "abc-123" } },
    body: { title: "Staff Engineer" },
  },
);

// DELETE
const { error: deleteError } = await apiClient.DELETE("/jobs/{jobId}", {
  params: { path: { jobId: "abc-123" } },
});
```

**Why good:** paths, parameters, request bodies, and responses are all type-checked against the spec. Typos in paths or invalid params are compile-time errors.

---

## Pattern 5: openapi-fetch Middleware

Middleware intercepts requests and responses. Use for auth headers, logging, and error handling.

### Auth Middleware

```typescript
import type { Middleware } from "openapi-fetch";

let accessToken: string | undefined;

const authMiddleware: Middleware = {
  async onRequest({ request }) {
    if (accessToken) {
      request.headers.set("Authorization", `Bearer ${accessToken}`);
    }
    return request;
  },
};

// Register middleware
apiClient.use(authMiddleware);

// Remove middleware later if needed
apiClient.eject(authMiddleware);
```

### Error Logging Middleware

```typescript
const loggingMiddleware: Middleware = {
  async onResponse({ request, response }) {
    if (!response.ok) {
      console.error(
        `API error: ${request.method} ${request.url} -> ${response.status}`,
      );
    }
    return response;
  },
};

apiClient.use(loggingMiddleware);
```

### Error Throwing Middleware

```typescript
const throwOnError: Middleware = {
  async onResponse({ response }) {
    if (!response.ok) {
      throw new Error(`${response.url}: ${response.status}`);
    }
    return response;
  },
};
```

**Execution order:** `onRequest` callbacks run in registration order. `onResponse` callbacks run in reverse order.

**Gotcha:** `onError` does NOT catch 4xx/5xx responses -- those are successful HTTP responses. Check `response.ok` or `response.status` in `onResponse` instead. `onError` only fires for network/fetch failures.

---

## Pattern 6: Response Handling Patterns

### Discriminated Error Handling

```typescript
const { data, error, response } = await apiClient.GET("/jobs/{jobId}", {
  params: { path: { jobId } },
});

// data and error are discriminated -- only one is defined
if (error) {
  // error is typed to the spec's error response schema
  switch (error.code) {
    case "not_found":
      // Handle 404
      break;
    case "unauthorized":
      // Handle 401
      break;
    default:
      // Unknown error
      break;
  }
  return;
}

// data is typed to the spec's 200 response schema
console.log(data.title);
```

### Accessing Response Headers

```typescript
const { data, response } = await apiClient.GET("/jobs", {
  params: { query: { page: 1 } },
});

// response is the raw Response object
const rateLimit = response.headers.get("X-RateLimit-Remaining");
const retryAfter = response.headers.get("Retry-After");
```

---

## Pattern 7: Programmatic Type Generation

Use the Node.js API when you need custom transforms (e.g., converting `date-time` strings to `Date` types).

```typescript
import fs from "node:fs";
import openapiTS, { astToString } from "openapi-typescript";
import ts from "typescript";

const DATE_TYPE = ts.factory.createTypeReferenceNode("Date");
const NULL_TYPE = ts.factory.createLiteralTypeNode(ts.factory.createNull());

const ast = await openapiTS(new URL("./api/openapi.yaml", import.meta.url), {
  transform(schemaObject) {
    // Convert date-time strings to Date type
    if (schemaObject.format === "date-time") {
      return Array.isArray(schemaObject.type) &&
        schemaObject.type.includes("null")
        ? ts.factory.createUnionTypeNode([DATE_TYPE, NULL_TYPE])
        : DATE_TYPE;
    }
  },
});

const contents = astToString(ast);
fs.writeFileSync("./api/schema.ts", contents);
```

**When to use programmatic API:** custom type transforms (Date, Blob), build pipeline integration, dynamic schema loading, adding validation annotations to generated types.

# OpenAPI Core Patterns

> Related: [codegen.md](codegen.md) for TypeScript generation, [validation.md](validation.md) for request/response validation

---

## Pattern 1: Complete Spec Structure

A production-ready OpenAPI 3.1 document with all major sections.

```yaml
openapi: "3.1.0"
info:
  title: Jobs API
  version: "1.0.0"
  description: |
    REST API for job listings, applications, and company profiles.
  contact:
    name: API Support
    email: api@example.com
  license:
    name: MIT
    identifier: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

tags:
  - name: Jobs
    description: Job listing operations
  - name: Companies
    description: Company profile operations

paths:
  /jobs:
    get:
      operationId: listJobs
      tags: [Jobs]
      summary: List job postings
      description: Returns a paginated list of active job postings.
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
            description: ISO 3166-1 alpha-2 country code
        - name: status
          in: query
          schema:
            type: string
            enum: [active, closed, draft]
            default: active
      responses:
        "200":
          description: Paginated list of jobs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

    post:
      operationId: createJob
      tags: [Jobs]
      summary: Create a job posting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateJobInput"
      responses:
        "201":
          description: Job created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
      security:
        - bearerAuth: []

  /jobs/{jobId}:
    get:
      operationId: getJob
      tags: [Jobs]
      summary: Get job details
      parameters:
        - $ref: "#/components/parameters/JobIdParam"
      responses:
        "200":
          description: Job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      operationId: updateJob
      tags: [Jobs]
      summary: Update a job posting
      parameters:
        - $ref: "#/components/parameters/JobIdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateJobInput"
      responses:
        "200":
          description: Job updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - bearerAuth: []

    delete:
      operationId: deleteJob
      tags: [Jobs]
      summary: Delete a job posting
      parameters:
        - $ref: "#/components/parameters/JobIdParam"
      responses:
        "204":
          description: Job deleted
        "404":
          $ref: "#/components/responses/NotFound"
      security:
        - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    JobIdParam:
      name: jobId
      in: path
      required: true
      schema:
        type: string
        format: uuid

    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    # --- Base schemas ---
    Pagination:
      type: object
      required: [page, limit, total, totalPages]
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code
          examples: ["validation_error", "not_found"]
        message:
          type: string
          description: Human-readable error description
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

    # --- Domain schemas ---
    Job:
      type: object
      required: [id, title, companyId, status, createdAt]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: ["string", "null"]
        companyId:
          type: string
          format: uuid
        salary:
          $ref: "#/components/schemas/Salary"
        status:
          type: string
          enum: [active, closed, draft]
        tags:
          type: array
          items:
            type: string
          default: []
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: ["string", "null"]
          format: date-time

    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

    CreateJobInput:
      type: object
      required: [title, companyId]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: ["string", "null"]
        companyId:
          type: string
          format: uuid
        salary:
          $ref: "#/components/schemas/Salary"
        tags:
          type: array
          items:
            type: string

    UpdateJobInput:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: ["string", "null"]
        salary:
          $ref: "#/components/schemas/Salary"
        status:
          type: string
          enum: [active, closed, draft]
        tags:
          type: array
          items:
            type: string

    JobListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Job"
        pagination:
          $ref: "#/components/schemas/Pagination"
```

---

## Pattern 2: Schema Composition with $ref

### allOf -- Extending a Base Schema

Use `allOf` when a schema includes everything from a base plus additional fields.

```yaml
# Base entity with audit fields
BaseEntity:
  type: object
  required: [id, createdAt, updatedAt]
  properties:
    id:
      type: string
      format: uuid
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time

# Job extends BaseEntity
Job:
  allOf:
    - $ref: "#/components/schemas/BaseEntity"
    - type: object
      required: [title, status]
      properties:
        title:
          type: string
        status:
          type: string
          enum: [active, closed, draft]
```

**Why good:** base fields defined once, changes propagate to all extending schemas, generated types reflect inheritance

### oneOf with Discriminator -- Polymorphism

Use `oneOf` with `discriminator` when the same field can hold different shapes identified by a type field.

```yaml
Notification:
  oneOf:
    - $ref: "#/components/schemas/EmailNotification"
    - $ref: "#/components/schemas/SmsNotification"
    - $ref: "#/components/schemas/PushNotification"
  discriminator:
    propertyName: type
    mapping:
      email: "#/components/schemas/EmailNotification"
      sms: "#/components/schemas/SmsNotification"
      push: "#/components/schemas/PushNotification"

EmailNotification:
  type: object
  required: [type, email, subject]
  properties:
    type:
      type: string
      const: email
    email:
      type: string
      format: email
    subject:
      type: string

SmsNotification:
  type: object
  required: [type, phone, message]
  properties:
    type:
      type: string
      const: sms
    phone:
      type: string
    message:
      type: string

PushNotification:
  type: object
  required: [type, deviceId, title]
  properties:
    type:
      type: string
      const: push
    deviceId:
      type: string
    title:
      type: string
```

**Why good:** explicit mapping aids code generators, `const` on discriminator field enables TypeScript narrowing, each variant is independently referenceable

**Gotcha:** `discriminator` only works with `$ref` entries in `oneOf` -- inline schemas are ignored by the discriminator.

---

### anyOf -- Flexible Matching

Use `anyOf` when a value can match one or more schemas simultaneously.

```yaml
# Address can be domestic, international, or both (e.g., border zones)
Address:
  anyOf:
    - $ref: "#/components/schemas/DomesticAddress"
    - $ref: "#/components/schemas/InternationalAddress"
```

**When to use `oneOf` vs `anyOf`:** Use `oneOf` when exactly one schema must match (mutually exclusive types). Use `anyOf` when multiple schemas could match simultaneously.

---

## Pattern 3: Reusable Parameters and Responses

Extract repeated parameters and error responses into `components`.

```yaml
components:
  parameters:
    # Reusable pagination params
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    # Reusable sort param
    SortParam:
      name: sort
      in: query
      schema:
        type: string
        enum: [createdAt, updatedAt, title]
        default: createdAt
    SortOrderParam:
      name: order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: desc

  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
```

**Usage in paths:**

```yaml
paths:
  /jobs:
    get:
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/SortParam"
        - $ref: "#/components/parameters/SortOrderParam"
      responses:
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/TooManyRequests"
```

**Why good:** error shapes are consistent across all endpoints, pagination params defined once, adding a new standard response is a single change

---

## Pattern 4: OpenAPI 3.1 vs 3.0 Syntax Differences

Key changes to be aware of when writing 3.1 specs.

### Nullable Fields

```yaml
# 3.1 (correct) -- type array with "null"
description:
  type: ["string", "null"]

# 3.0 (outdated) -- nullable keyword removed in 3.1
# description:
#   type: string
#   nullable: true
```

### Exclusive Min/Max

```yaml
# 3.1 -- exclusiveMinimum is a number
age:
  type: integer
  exclusiveMinimum: 0 # Must be > 0


# 3.0 (outdated) -- exclusiveMinimum was a boolean
# age:
#   type: integer
#   minimum: 0
#   exclusiveMinimum: true
```

### $ref with Siblings

```yaml
# 3.1 -- $ref can have sibling keywords (description overrides)
salary:
  $ref: "#/components/schemas/Salary"
  description: Override the referenced schema's description

# 3.0 -- siblings next to $ref were ignored
```

### const Keyword

```yaml
# 3.1 -- const for fixed values (from JSON Schema)
type:
  type: string
  const: email

# 3.0 -- had to use single-value enum
# type:
#   type: string
#   enum: [email]
```

### examples Keyword

```yaml
# 3.1 -- examples as array (JSON Schema standard)
email:
  type: string
  format: email
  examples: ["user@example.com", "admin@example.com"]

# 3.0 -- single example keyword
# email:
#   type: string
#   format: email
#   example: "user@example.com"
```

---

## Pattern 5: Security Schemes

Define authentication methods in `components/securitySchemes` and apply globally or per-operation.

```yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read:jobs: Read job listings
            write:jobs: Create and update jobs

# Apply globally (all operations require auth)
security:
  - bearerAuth: []

# Override per-operation (public endpoint)
paths:
  /jobs:
    get:
      operationId: listJobs
      security: [] # No auth required
```

**Why good:** security defined once, applied consistently, per-operation overrides for public endpoints

# Request/Response Validation

> Related: [core.md](core.md) for spec structure, [codegen.md](codegen.md) for type generation

---

## Pattern 1: Spec Validation and Linting

Validate your OpenAPI spec for correctness before generating types or publishing documentation. Catch structural errors, missing `$ref` targets, and convention violations early.

### Redocly CLI

```bash
# Install
npm install -D @redocly/cli

# Lint a spec
npx redocly lint ./api/openapi.yaml

# Bundle multi-file specs into a single file
npx redocly bundle ./api/openapi.yaml -o ./api/bundled.yaml

# Preview docs locally
npx redocly preview-docs ./api/openapi.yaml
```

### redocly.yaml Configuration

```yaml
# redocly.yaml
extends:
  - recommended

rules:
  # Require operationId on every operation
  operation-operationId: error

  # Require descriptions on operations
  operation-description: warn

  # Require tags on operations
  operation-tag-defined: error

  # Reject unused components
  no-unused-components: warn

  # Require info contact
  info-contact: warn
```

**Why good:** catches missing `operationId`, broken `$ref`, unused schemas, and convention violations before they reach codegen

---

## Pattern 2: Runtime Validation Strategies

### Spec-Derived Validation (Recommended)

When you write the spec first, derive runtime validation from it. The spec is the single source of truth for both types AND validation rules.

**Strategy 1: Generate Zod schemas from spec**

```bash
# Generate Zod schemas from OpenAPI spec
npx @hey-api/openapi-ts \
  -i ./api/openapi.yaml \
  -o ./api/generated \
  -p @hey-api/zod
```

This generates Zod schemas matching your OpenAPI schemas. Your validation layer uses generated schemas, keeping validation in sync with the spec automatically.

**Strategy 2: Framework-native validation from spec**

Many API frameworks read the OpenAPI spec directly and validate incoming requests against it at the middleware level. The spec defines the validation rules, the framework enforces them -- no separate validation code to maintain.

### Code-Derived Spec (Alternative)

When you write validation schemas first (code-first), generate the spec from them. Libraries like `zod-to-openapi` or framework-specific OpenAPI integrations derive the OpenAPI spec from your Zod schemas.

```typescript
// Code-first: Zod schema IS the source of truth
// OpenAPI spec is generated from it
// (import z from your framework's OpenAPI integration)
import { z } from "zod-to-openapi";

const CreateJobSchema = z
  .object({
    title: z.string().min(1).max(200),
    companyId: z.string().uuid(),
  })
  .openapi("CreateJobInput");
```

**When to use code-first:** Framework provides first-class OpenAPI generation, rapid prototyping, single-team internal APIs.

---

## Pattern 3: Request Validation Patterns

Regardless of spec-first or code-first, these patterns apply to validating incoming requests.

### Path Parameter Validation

```yaml
# In the spec
parameters:
  - name: jobId
    in: path
    required: true
    schema:
      type: string
      format: uuid
```

The `format: uuid` constraint should be enforced at runtime. Either your framework validates against the spec, or your validation layer checks the format.

### Query Parameter Validation with Defaults

```yaml
parameters:
  - name: page
    in: query
    schema:
      type: integer
      minimum: 1
      default: 1
  - name: limit
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20
  - name: sort
    in: query
    schema:
      type: string
      enum: [createdAt, updatedAt, title]
      default: createdAt
```

**Key point:** Query params arrive as strings over HTTP. Your validation layer must coerce `"20"` to `20` for integer params.

### Request Body Validation

```yaml
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/CreateJobInput"
```

The `required: true` means the body must be present. The schema's own `required` array defines which fields within the body are mandatory.

---

## Pattern 4: Response Validation

Validate outgoing responses in development/testing to catch implementation drift from the spec.

### Development-Time Response Validation

```typescript
// Only in development -- validate responses match spec
function validateResponse(
  path: string,
  method: string,
  statusCode: number,
  body: unknown,
): void {
  if (process.env.NODE_ENV !== "development") return;

  // Use your spec validation library to check body against
  // the response schema for this path/method/status
  const isValid = specValidator.validateResponse(
    path,
    method,
    statusCode,
    body,
  );

  if (!isValid) {
    console.warn(
      `Response for ${method.toUpperCase()} ${path} (${statusCode}) does not match spec`,
      specValidator.errors,
    );
  }
}
```

**Why validate responses:** Catches implementation bugs where the handler returns data that doesn't match the spec. Run in development/CI, not production.

---

## Pattern 5: Error Response Contract

Define a consistent error shape in the spec and enforce it across all endpoints.

```yaml
components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code
          examples: ["validation_error", "not_found", "unauthorized"]
        message:
          type: string
          description: Human-readable message
        details:
          type: array
          items:
            type: object
            required: [field, message]
            properties:
              field:
                type: string
              message:
                type: string
```

### Consistent Error Formatting

```typescript
// Named error codes from the spec
const ERROR_CODES = {
  VALIDATION_ERROR: "validation_error",
  NOT_FOUND: "not_found",
  UNAUTHORIZED: "unauthorized",
  FORBIDDEN: "forbidden",
  INTERNAL_ERROR: "internal_error",
} as const;

interface ApiError {
  code: string;
  message: string;
  details?: Array<{ field: string; message: string }>;
}

function formatValidationError(
  issues: Array<{ path: string; message: string }>,
): ApiError {
  return {
    code: ERROR_CODES.VALIDATION_ERROR,
    message: "Validation failed",
    details: issues.map((issue) => ({
      field: issue.path,
      message: issue.message,
    })),
  };
}

function formatNotFoundError(resource: string, id: string): ApiError {
  return {
    code: ERROR_CODES.NOT_FOUND,
    message: `${resource} with id '${id}' not found`,
  };
}
```

**Why good:** every endpoint returns the same error shape, clients can reliably parse errors, machine-readable codes enable programmatic handling

---

## Pattern 6: CI Pipeline Integration

Validate specs and check type freshness in CI to prevent drift.

```bash
# 1. Lint the spec
npx redocly lint ./api/openapi.yaml

# 2. Check if generated types are up to date
npx openapi-typescript ./api/openapi.yaml --check

# 3. Type-check the project (catches mismatches between generated types and code)
npx tsc --noEmit
```

**`--check` flag:** Compares the current generated file against what the spec would produce. Fails if they differ -- forces developers to regenerate types after spec changes.

### package.json Scripts

```json
{
  "scripts": {
    "api:lint": "redocly lint ./api/openapi.yaml",
    "api:generate": "openapi-typescript ./api/openapi.yaml -o ./api/schema.d.ts",
    "api:check": "openapi-typescript ./api/openapi.yaml --check",
    "precommit": "npm run api:lint && npm run api:check && tsc --noEmit"
  }
}
```