openapi-to-typescript_skill

Overview

This skill converts OpenAPI 3.0 JSON or YAML specifications into idiomatic TypeScript interfaces, type aliases, and runtime type guards. It generates request/response types for endpoints, resolves component references to named types, and emits a compact header and error types suitable for direct inclusion in a codebase. Use it to keep TypeScript types synchronized with your API contract and to add safe runtime checks.

How this skill works

The tool validates the OpenAPI file (must start with openapi: "3.0" and include paths and components.schemas) and extracts schemas from components/schemas and operation shapes from paths. It maps OpenAPI primitives, formats, enums, arrays, oneOf/allOf constructs, and $ref to TypeScript primitives, interfaces, unions, intersections, and named references. The generator also emits JSDoc from descriptions and creates type guard functions that verify required fields and runtime types.

When to use it

• You need TypeScript interfaces and type guards from an OpenAPI 3.0 spec
• Converting an API schema (JSON or YAML) into a single types file
• Generating request and response types for client code or SDKs
• Adding runtime validation helpers for API responses
• Automating type updates when the API contract changes

Best practices

• Validate the OpenAPI file first; the generator only supports 3.0.x and requires paths and components.schemas when types exist
• Keep descriptive schema descriptions to generate useful JSDoc comments
• Prefer $ref to reuse component schemas rather than inlining identical objects
• Review generated type guards for complex unions or circular references and adjust as needed
• Save output to a dedicated file (default: types/api.ts) and include it in your build

Example use cases

• Generate Product, User, and ApiError interfaces from components/schemas for a frontend app
• Produce Request/Response types for each endpoint to strongly type API client functions
• Create runtime type guards to validate JSON responses from fetch or axios before use
• Automate type generation in CI so types stay in sync with API spec changes
• Convert a third-party OpenAPI file into TypeScript types for integration work