openapi-to-typescript
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.
By softaworks · 3,907 installs
npx skills add softaworks/agent-toolkit --skill openapi-to-typescript
Source repository · Upstream listing
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