Openapi To Typescript

If invalid, report the error and stop.

Type Mapping

Primitives

Format Modifiers

Complex Types

Object:

// OpenAPI: type: object, properties: {id, name}, required: [id]
interface Example {
  id: string;      // required: no ?
  name?: string;   // optional: with ?
}

Array:

// OpenAPI: type: array, items: {type: string}
type Names = string[];

Enum:

// OpenAPI: type: string, enum: [active, draft]
type Status = "active" | "draft";

oneOf (Union):

// OpenAPI: oneOf: [{$ref: Cat}, {$ref: Dog}]
type Pet = Cat | Dog;

allOf (Intersection/Extends):

// OpenAPI: allOf: [{$ref: Base}, {type: object, properties: ...}]
interface Extended extends Base {
  extraField: string;
}

Code Generation

File Header

/**
 * Auto-generated from: {source_file}
 * Generated at: {timestamp}
 *
 * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
 */

Interfaces (from components/schemas)

For each schema in components/schemas:

export interface Product {
  /** Product unique identifier */
  id: string;

  /** Product title */
  title: string;

  /** Product price */
  price: number;

  /** Created timestamp */
  created_at?: string;
}

• Use OpenAPI description as JSDoc
• Fields in required[] have no ?
• Fields outside required[] have ?

Request/Response Types (from paths)

For each endpoint in paths:

// GET /products - query params
export interface GetProductsRequest {
  page?: number;
  limit?: number;
}

// GET /products - response 200
export type GetProductsResponse = ProductList;

// POST /products - request body
export interface CreateProductRequest {
  title: string;
  price: number;
}

// POST /products - response 201
export type CreateProductResponse = Product;

Naming convention:

• {Method}{Path}Request for params/body
• {Method}{Path}Response for response

Type Guards

For each main interface, generate a type guard:

export function isProduct(value: unknown): value is Product {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    typeof (value as any).id === 'string' &&
    'title' in value &&
    typeof (value as any).title === 'string' &&
    'price' in value &&
    typeof (value as any).price === 'number'
  );
}

Type guard rules:

• Check typeof value === 'object' && value !== null
• For each required field: check 'field' in value
• For primitive fields: check typeof
• For arrays: check Array.isArray()
• For enums: check .includes()

Error Type (always include)

export interface ApiError {
  status: number;
  error: string;
  detail?: string;
}

export function isApiError(value: unknown): value is ApiError {
  return (
    typeof value === 'object' &&
    value !== null &&
    'status' in value &&
    typeof (value as any).status === 'number' &&
    'error' in value &&
    typeof (value as any).error === 'string'
  );
}

$ref Resolution

When encountering {"$ref": "#/components/schemas/Product"}:

1. Extract the schema name (Product)
2. Use the type directly (don't resolve inline)

// OpenAPI: items: {$ref: "#/components/schemas/Product"}
// TypeScript: