Openapi To Typescript

# OpenAPI to TypeScript

A Claude Code skill that converts OpenAPI 3.0 specifications (JSON or YAML) into TypeScript interfaces and type guards.

## Purpose

This skill automates the process of generating type-safe TypeScript code from OpenAPI API specifications. It creates:
- TypeScript interfaces for all schema definitions
- Request/Response type definitions for API endpoints
- Runtime type guards for validation
- Proper handling of complex types (unions, intersections, enums, arrays)

## When to Use

Use this skill when you need to:
- Generate TypeScript types from an OpenAPI specification
- Create type-safe API client interfaces
- Convert API documentation into TypeScript code
- Maintain type safety between backend API specs and frontend code

### Trigger Phrases

- "generate types from openapi"
- "convert openapi to typescript"
- "create API interfaces"
- "generate types from spec"
- "convert schema to TS"

## How It Works

### Workflow

1. **Request Input**: Asks for the OpenAPI file path (if not provided)
2. **Validation**: Reads and validates the OpenAPI specification (must be 3.0.x)
3. **Schema Extraction**: Extracts schemas from `components/schemas`
4. **Endpoint Analysis**: Extracts request/response types from `paths`
5. **Code Generation**: Generates TypeScript interfaces and type guards
6. **Output**: Asks where to save (default: `types/api.ts`)
7. **Write File**: Creates the TypeScript file

### OpenAPI Support

- **Version**: OpenAPI 3.0.x only
- **Format**: JSON or YAML
- **Required fields**: `openapi`, `paths`, `components.schemas`

## Key Features

### Type Mapping

**Primitives**:
- `string` → `string`
- `number` / `integer` → `number`
- `boolean` → `boolean`
- `null` → `null`

**Format Modifiers** (with JSDoc comments):
- `uuid` → `string` (/** UUID */)
- `date` → `string` (/** Date */)
- `date-time` → `string` (/** ISO DateTime */)
- `email` → `string` (/** Email */)
- `uri` → `string` (/** URI */)

**Complex Types**:
- **Objects** → TypeScript interfaces with optional/required fields
- **Arrays** → TypeScript array types (`Type[]`)
- **Enums** → TypeScript union types (`"value1" | "value2"`)
- **oneOf** → Union types (`Type1 | Type2`)
- **allOf** → Interface extension (`extends`)
- **$ref** → Direct type references

### Generated Code Structure

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

// Types
export interface User { ... }
export type Status = "active" | "draft";

// Request/Response Types
export interface GetUsersRequest { ... }
export type GetUsersResponse = User[];

// Type Guards
export function isUser(value: unknown): value is User { ... }

// Error Types (always included)
export interface ApiError { ... }
export function isApiError(value: unknown): value is ApiError { ... }
```

### Type Guards

Runtime validation functions for each interface:
- Check object structure
- Validate required fields
- Type-check primitives
- Validate enums and arrays

## Usage Examples

### Basic Usage

```
User: Generate TypeScript types from my OpenAPI spec at ./api/openapi.json

Claude: I'll convert your OpenAPI specification to TypeScript.
[Reads file, validates, generates types, saves to types/api.ts]
```

### With Custom Output Path

```
User: Convert openapi.yaml to TypeScript and save it to src/types/backend.ts

Claude: I'll generate TypeScript types from your OpenAPI spec.
[Generates and saves to specified location]
```

### Example Input/Output

**Input** (openapi.json):
```json
{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "name": {"type": "string"},
          "price": {"type": "number"},
          "status": {"type": "string", "enum": ["active", "draft"]}
        },
        "required": ["id", "name", "price", "status"]
      }
    }
  },
  "paths": {
    "/pr