openapi-to-typescript

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 Request the OpenAPI file path (if not provided) Read and validate the file (must be OpenAPI 3.0.x) Extract schemas from components/schemas Extract endpoints from paths (request/response types) Generate TypeScript (interfaces + type guards) Ask where to save (default: types/api.ts in current directory) Write the file OpenAPI Validation Check before processing: - Field "openapi" must exist and start with "3.0" - Field "paths" must exist - Field "components.schemas" must exist (if there are types) 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: // 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"} : Extract the schema name ( Product ) Use the type directly (don't resolve inline) // OpenAPI: items: {$ref: "#/components/schemas/Product"} // TypeScript: items : Product [ ] // reference, not inline Complete Example Input (OpenAPI): { "openapi" : "3.0.0" , "components" : { "schemas" : { "User" : { "type" : "object" , "properties" : { "id" : { "type" : "string" , "format" : "uuid" } , "email" : { "type" : "string" , "format" : "email" } , "role" : { "type" : "string" , "enum" : [ "admin" , "user" ] } } , "required" : [ "id" , "email" , "role" ] } } } , "paths" : { "/users/{id}" : { "get" : { "parameters" : [ { "name" : "id" , "in" : "path" , "required" : true } ] , "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/User" } } } } } } } } } Output (TypeScript): / * Auto-generated from: api.openapi.json * Generated at: 2025-01-15T10:30:00Z * * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema / // ============================================================================ // Types // ============================================================================ export type UserRole = "admin" | "user" ; export interface User { / UUID */ id : string ; / Email */ email : string ; role : UserRole ; } // ============================================================================ // Request/Response Types // ============================================================================ export interface GetUserByIdRequest { id : string ; } export type GetUserByIdResponse = User ; // ============================================================================ // Type Guards // ============================================================================ export function isUser ( value : unknown ) : value is User { return ( typeof value === 'object' && value !== null && 'id' in value && typeof ( value as any ) . id === 'string' && 'email' in value && typeof ( value as any ) . email === 'string' && 'role' in value && [ 'admin' , 'user' ] . includes ( ( value as any ) . role ) ) ; } // ============================================================================ // Error Types // ============================================================================ 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' ) ; } 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