@nomagick/openapi-dts

Generate TypeScript .d.ts declaration files from OpenAPI 3.0 specs.

This project is 100% AI generated code, written by Claude (Anthropic).

Usage

npx @nomagick/openapi-dts <input> [output]

• input — path to a local openapi.json file or an https:// URL
• output — output file path (default: api.d.ts)

Examples

npx @nomagick/openapi-dts ./openapi.json
npx @nomagick/openapi-dts ./openapi.json types/api.d.ts
npx @nomagick/openapi-dts https://r.jina.ai/openapi.json jina.d.ts

Output structure

The generated file exports:

Individual types — every component schema is exported at the top level for direct import:

import type { CrawlerOptions, FormattedPageDto } from './api';

components interface — OpenAPI-style structured access by original schema key:

import type { components } from './api';
type Opts = components['schemas']['CrawlerOptions@0x25'];

paths interface — typed parameters and responses per operation:

import type { paths } from './api';
type Query = paths['/']['get']['parameters']['query'];
type Result = paths['/']['post']['response'];

Naming conventions

| Schema type | Example name | |---|---| | Named schema with clean title | CrawlerOptions, Cookie | | String literal union (enum) | Literal0x0c | | Array schema | Array0x27 | | Record schema | Record0x28 |

Response simplification

• Opaque string content types (text/plain, text/event-stream, binary streams) are omitted
• When a single meaningful content type remains, the content/mime wrapper is removed
• When only one status code is documented, the status code wrapper is removed — the field becomes response: T instead of responses: { 200: T }

Requirements

Node.js 18 or later.