Openapi To Typescript

by softaworks3027f20f3181No license2.5K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 7 months ago

Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards. This skill should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification.

Instructions onlySoftware Development

AI-generated overview

Converts OpenAPI 3.0 JSON or YAML specifications into TypeScript interfaces, request/response types and type guards.

What it does: Reads an OpenAPI 3.0.x specification file, validates it, and extracts schemas from components/schemas and endpoints from paths. It then generates a TypeScript file containing exported interfaces, request and response types, type guards, and a standard ApiError type, mapping OpenAPI primitives, formats, enums, arrays, oneOf and allOf constructs. The generated file is written to a chosen location, defaulting to types/api.ts in the current directory.
When to use it: Use it when you need TypeScript types generated from an OpenAPI specification, such as creating API interfaces or converting a schema to TypeScript. It fits requests to generate types from a spec or produce typed API client models.
Requirements: An OpenAPI 3.0.x file in JSON or YAML as input, and a writable destination path for the generated TypeScript file. It ships no scripts; the workflow is instructions only.

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)

- 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

Format Modifiers

Complex Types

Object:

typescript

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

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

Array:

Enum:

oneOf (Union):

allOf (Intersection/Extends):

typescript

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

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

Code Generation

File Header

typescript

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

/** * 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:

typescript

export interface Product {  /** Product unique identifier */  id: string;
  /** Product title */  title: string;
  /** Product price */  price: number;
  /** Created timestamp */  created_at?: string;}

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:

typescript

// GET /products - query paramsexport interface GetProductsRequest {  page?: number;  limit?: number;}
// GET /products - response 200export type GetProductsResponse = ProductList;
// POST /products - request bodyexport interface CreateProductRequest {  title: string;  price: number;}
// POST /products - response 201export type CreateProductResponse = Product;

// GET /products - query paramsexport interface GetProductsRequest {  page?: number;  limit?: number;}
// GET /products - response 200export type GetProductsResponse = ProductList;
// POST /products - request bodyexport interface CreateProductRequest {  title: string;  price: number;}
// POST /products - response 201export 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:

typescript

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'  );}

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)

typescript

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'  );}

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)

typescript

// OpenAPI: items: {$ref: "#/components/schemas/Product"}// TypeScript:items: Product[]  // reference, not inline

// OpenAPI: items: {$ref: "#/components/schemas/Product"}// TypeScript:items: Product[]  // reference, not inline

Complete Example

Input (OpenAPI):

json

{  "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"}              }            }          }        }      }    }  }}

{  "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):

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'  );}

/** * 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

Source and attribution

Source:softaworks/agent-toolkitinskills/openapi-to-typescriptat commit3027f20

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

OpenAPI	TypeScript
`string`	`string`
`number`	`number`
`integer`	`number`
`boolean`	`boolean`
`null`	`null`

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

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

Openapi To Typescript

OpenAPI to TypeScript

When to Use

Workflow

OpenAPI Validation

Type Mapping

Primitives

Format Modifiers

Complex Types

Code Generation

File Header

Interfaces (from components/schemas)

Request/Response Types (from paths)

Type Guards

Error Type (always include)

$ref Resolution

Complete Example

Common Errors

Source and attribution

More from softaworks/agent-toolkit

C4 Architecture

Writing Clearly And Concisely

Web To Markdown

Skill Judge

Ship Learn Next

Reducing Entropy

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices