Skip to content

README.md

Latest commit

 

History

History
148 lines (112 loc) · 8.99 KB

README.md

File metadata and controls

148 lines (112 loc) · 8.99 KB
Raw

Important announcement

Important

Please migrate your projects to use @hey-api/openapi-ts

Due to time limitations on my end, this project has been unmaintained for a while now. The @hey-api/openapi-ts project started as a fork with the goal to resolve the most pressing issues. going forward they are planning to maintain the OpenAPI generator and give it the love it deserves. Please support them with their work and make sure to migrate your projects: https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen

  • All open PR's and issues will be archived on the 1st of May 2024
  • All versions of this package will be deprecated in NPM

👋 Thanks for all the support, downloads and love! Cheers Ferdi.

OpenAPI Typescript Codegen

NPM License Downloads Build

Node.js library that generates Typescript clients based on the OpenAPI specification.

Why?

  • Frontend ❤️ OpenAPI, but we do not want to use JAVA codegen in our builds
  • Quick, lightweight, robust and framework-agnostic 🚀
  • Supports generation of TypeScript clients
  • Supports generations of Fetch, Node-Fetch, Axios, Angular and XHR http clients
  • Supports OpenAPI specification v2.0 and v3.0
  • Supports JSON and YAML files for input
  • Supports generation through CLI, Node.js and NPX
  • Supports tsc and @babel/plugin-transform-typescript
  • Supports aborting of requests (cancelable promise pattern)
  • Supports external references using json-schema-ref-parser

Fork divergence

This is a maintained fork of openapi-typescript-codegen. All core behavior is preserved; the differences below are additive and only affect the fetch client. Other clients (axios, xhr, node, angular) are unchanged from upstream.

The additions cover three cross-cutting concerns that consumers otherwise need to bolt on via post-generation hand-edits: response caching, opt-in file downloads, and session-expiry detection.

Extended OpenAPIConfig fields

All new fields are optional and default to undefined/false, so a consumer that sets nothing gets vanilla upstream behavior.

Field Type Purpose
CACHE_OPTIONS { enabled: boolean; ttl?: number; key?: string; featureToggled?: boolean } Per-call caching policy. Passed via configOverrides on a service method: Service.get(id, { CACHE_OPTIONS: { enabled: true, key: 'foo' } }). If enabled is true and CACHE_PROVIDER is configured, the request is served from cache on hit and stored on miss. The store is not awaited: the request resolves as soon as the response is read.
CACHE_PROVIDER CacheProvider (structural: getItem, setItem, optional removeItem / destroy) Pluggable cache backend. The generator ships no implementation — wire in your own (IndexedDB, localStorage, in-memory Map, etc.) at init time: OpenAPI.CACHE_PROVIDER = myCache;. Cache keys default to JSON.stringify(options) unless CACHE_OPTIONS.key is set.
ON_CACHE_ERROR (operation: 'getItem' | 'setItem', error: unknown, cacheKey: string) => void Invoked when the cache provider rejects. Cache I/O is never fatal: a failed read falls through to the network, a failed write is ignored. Typical use: log, or remove the entry a corrupted read came from.
CACHE_TIMEOUT number (ms) Upper bound on a cache read. When it elapses the read counts as a miss and the request goes to the network. Unset (the default) waits for the read as long as it takes.
ON_CACHE_TIMEOUT (operation: 'getItem', cacheKey: string, pending: Promise<unknown>) => void Invoked when a read exceeds CACHE_TIMEOUT. pending is the read still outstanding; it settling tells you the cache has come back. That request does not write its response back, so writes don't queue up against a cache that isn't answering. Typical use: a circuit breaker that detaches CACHE_PROVIDER until then.
SMART_DOWNLOAD boolean Two effects when true: (1) the response is parsed as text even under a JSON content-type (useful for endpoints that return raw YAML/XML with the wrong Content-Type), and (2) if the response carries Content-Disposition: attachment, a browser "Save file" dialog is triggered automatically. Non-attachment responses flow through unchanged.
REDIRECT RequestRedirect ('follow' | 'error' | 'manual') Forwarded to fetch's RequestInit.redirect. Default is the browser's native default ('follow'). Set to 'manual' if you want to observe session-expiry redirects via ON_OPAQUE_REDIRECT.
ON_OPAQUE_REDIRECT (response: Response) => void Invoked when fetch returns a response with type === 'opaqueredirect' (only possible when REDIRECT: 'manual' is set). Typical use: clear the cache, show a "session expired" modal, redirect to login.

Built-in file-download behavior

When SMART_DOWNLOAD: true, the generated request.ts includes three internal helpers that implement the download pipeline — no consumer code or hooks required:

  • handleFileDownload — bails out unless Content-Disposition: attachment is present; silent no-op otherwise.
  • getContentDispositionFilename — parses the header. Handles RFC 5987 filename*=UTF-8''..., quoted filename="...", and bare filename=.... Falls back to 'download'. For exotic cases (non-UTF-8 extended params, multi-line continuations) swap for the content-disposition npm package.
  • downloadBlob — standard synthetic-anchor + URL.createObjectURL + click + revoke routine. Browser-only.

Example consumer wiring

import { OpenAPI } from './generated/open-api';
import { MyCache } from './my-cache';

OpenAPI.BASE = '/api';
OpenAPI.CACHE_PROVIDER = new MyCache();
OpenAPI.REDIRECT = 'manual';
OpenAPI.ON_OPAQUE_REDIRECT = () => {
    OpenAPI.CACHE_PROVIDER?.destroy?.({ clearData: true });
    showSessionExpiredModal();
};

// Per-call usage:
await MyService.getThing(id, { CACHE_OPTIONS: { enabled: true, key: `thing:${id}` } });
await MyService.exportCsv({ SMART_DOWNLOAD: true });

Install

npm install openapi-typescript-codegen --save-dev

Usage

$ openapi --help

  Usage: openapi [options]

  Options:
    -V, --version             output the version number
    -i, --input <value>       OpenAPI specification, can be a path, url or string content (required)
    -o, --output <value>      Output directory (required)
    -c, --client <value>      HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
    --name <value>            Custom client class name
    --useOptions              Use options instead of arguments
    --useUnionTypes           Use union types instead of enums
    --exportCore <value>      Write core files to disk (default: true)
    --exportServices <value>  Write services to disk (default: true)
    --exportModels <value>    Write models to disk (default: true)
    --exportSchemas <value>   Write schemas to disk (default: false)
    --indent <value>          Indentation options [4, 2, tab] (default: "4")
    --postfixServices         Service name postfix (default: "Service")
    --postfixModels           Model name postfix
    --request <value>         Path to custom request file
    -h, --help                display help for command

  Examples
    $ openapi --input ./spec.json --output ./generated
    $ openapi --input ./spec.json --output ./generated --client xhr

Documentation

The main documentation can be found in the openapi-typescript-codegen/wiki

Sponsors

If you or your company use the OpenAPI Typescript Codegen, please consider supporting me. By sponsoring I can free up time to give this project some love! Details can be found here: https://github.com/sponsors/ferdikoomen

If you're from an enterprise looking for a fully managed SDK generation, please consider our sponsor:

speakeasy