skills.rest
leonardoacosta
leonardoacostaCOMMUNITY
Explore all skills by this author →
GitHub

openapi-to-typescript

Converts OpenAPI 3.0 specifications into TypeScript interfaces and type guards.

Updated Aug 2, 2026
Search Tags:#typescript#type guards#interfaces#openapi#code generation#api types#schema conversion
One-click install
npx skills add https://github.com/leonardoacosta/skills --skill openapi-to-typescript-leonardoacosta
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openapi-to-typescript
Source: https://github.com/leonardoacosta/skills/tree/main/t3-stack-kit/skills/openapi-to-typescript
Command: npx skills add https://github.com/leonardoacosta/skills --skill openapi-to-typescript-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Manually translating OpenAPI 3.0 schemas into TypeScript types is error-prone: nullable-vs-optional fields, undiscriminated oneOf unions, allOf override conflicts, and circular $refs all produce types that compile but are silently wrong at runtime. This Skill encodes those spec semantics so generated interfaces and type guards match the actual wire format. ## Core Features & Use Cases - Schema-to-interface generation: Converts components/schemas into TypeScript interfaces with correct required/optional/nullable handling and JSDoc from descriptions. - Endpoint typing: Generates {Method}{Path}Request/Response types from paths, including shared parameter $refs. - Type guard generation: Emits runtime guards with honest limitations — primitive shape checks only, no format validation, and explicit ambiguity flags for undiscriminated oneOf. - Use Case: Given a payments API spec with a User schema and GET /users/{id} endpoint, generate a types/api.ts file containing the User interface, GetUserByIdRequest/Response types, isUser guard, and the standard ApiError type. ## Quick Start Generate TypeScript interfaces and type guards from my OpenAPI spec at api.openapi.json and save them to types/api.ts.

Frequently Asked Questions about openapi-to-typescript

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate TypeScript types from an OpenAPI spec?▼

Provide the OpenAPI 3.0 JSON or YAML file path, and the workflow extracts components/schemas into interfaces and paths into request/response types. Output is written to a TypeScript file, defaulting to types/api.ts, with interfaces, type guards, and an ApiError type.

How should nullable required fields map to TypeScript in OpenAPI?▼

A field that is both in required[] and nullable: true must become field: T | null, never field?: T. OpenAPI treats nullability and optionality as independent flags — the key is always present, only its value may be null.

Does a generated type guard validate uuid or date-time formats?▼

No. Format constraints like uuid, date-time, and email all map to plain string in TypeScript, and the generated guard only checks typeof === 'string'. Any string passes, so format enforcement needs separate runtime validation such as a regex or library.

Why is a oneOf type guard unsafe without a discriminator?▼

Without discriminator.propertyName, disambiguating union members requires structural probing, and members sharing fields can make the guard return true for the wrong member. The correct approach is to flag the ambiguity in the generated file rather than silently guess.

Which OpenAPI versions are supported for TypeScript conversion?▼

Only OpenAPI 3.0.x is supported. The workflow validates that the openapi field exists and starts with 3.0, and that paths and components.schemas are present, reporting an error and stopping otherwise.

How are circular $ref chains handled in generated types?▼

Circular references like A -> B -> A are broken with a named type alias that references the other type by name instead of inlining an object literal. Naive inlining recurses forever, so the named-alias approach is a structural requirement.

Related Skills

Explore More Software Engineering Skills→
davila7davila7
30.5k

openapi-to-typescript

Converts OpenAPI 3.0 JSON or YAML specifications into TypeScript interfaces and runtime type guards.

Community
Intermediate
saajunaidsaajunaid

api-client-patterns

Provide patterns for typed API clients with fetch wrappers and Zod validation.

Community
Advanced
vladm3105vladm3105
16

contract-tester

Validate API contracts and detect breaking changes across OpenAPI/AsyncAPI specifications.

Community
Advanced
rnavarychrnavarych
14

role-fullstack:api-frontend-integration

Integrate backend APIs with frontend apps using tRPC, OpenAPI codegen, and TanStack Query.

Community
Advanced