Openapi To Typescript @softaworks

OpenAPI to TypeScript

Converts OpenAPI 3.0 specifications to TypeScript interfaces and type guards.

Input: OpenAPI file (JSON or YAML) Output: TypeScript file with interfaces and type guards

When to Use

• "generate types from openapi"
• "convert openapi to typescript"
• "create API interfaces"
• "generate types from spec"

Workflow

1. Request the OpenAPI file path (if not provided)
2. Read and validate the file (must be OpenAPI 3.0.x)
3. Extract schemas from components/schemas
4. Extract endpoints from paths (request/response types)
5. Generate TypeScript (interfaces + type guards)
6. Ask where to save (default: types/api.ts in current directory)
7. Write the file

OpenAPI Validation

Check before processing:

If invalid, report the error and stop.

Type Mapping

Primitives

| OpenAPI | TypeScript | |-------------|--------------| | string | string | | number | number | | integer | number | | boolean | boolean | | null | null |

Format Modifiers

| Format | TypeScript | |---------------|-------------------------| | uuid | string (comment UUID) | | date | string (comment date) | | date-time | string (comment ISO) | | email | string (comment email)| | uri | string (comment URI) |

Complex Types

Object:

Array:

Enum:

oneOf (Union):

allOf (Intersection/Extends):

Code Generation

File Header

Interfaces (from components/schemas)

For each schema in components/schemas:

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

Request/Response Types (from paths)

For each endpoint in paths:

Naming convention:

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

Type Guards

For each main interface, generate a type guard:

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)

$ref Resolution

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

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

Complete Example

Input (OpenAPI):

Output (TypeScript):

Common Errors

| Error | Action | |-------|--------| | OpenAPI version != 3.0.x | Report that only 3.0 is supported | | $ref not found | List missing refs | | Unknown type | Use unknown and warn | | Circular reference | Use type alias with lazy reference |

• "generate types from openapi"
• "convert openapi to typescript"
• "create API interfaces"
• "generate types from spec"