openapi-typescript
    TypeScript icon, indicating that this package has built-in type declarations

    4.4.0 • Public • Published

    version(scoped) npm downloads (weekly) codecov

    All Contributors

    📘️ openapi-typescript

    🚀 Convert OpenAPI 3.0 and 2.0 (Swagger) schemas to TypeScript interfaces using Node.js.

    Features

    • OpenAPI 3.0
    • Swagger 2.0
    • Supports YAML and JSON schema formats
    • Supports loading via remote URL (simple authentication supported with the --auth flag)
    • Supports remote references: $ref: "external.yaml#components/schemas/User"
    • Formats using Prettier
    • TypeScript 4.0 features

    Examples

    Usage

    🖥️ CLI

    🗄️ Reading specs from file system

    npx openapi-typescript schema.yaml --output schema.ts
    
    # 🔭 Loading spec from schema.yaml…
    # 🚀 schema.yaml -> schema.ts [250ms]
    
    npx openapi-typescript "specs/**/*.yaml" --output schemas/
    
    # 🔭 Loading spec from specs/one.yaml…
    # 🔭 Loading spec from specs/two.yaml…
    # 🔭 Loading spec from specs/three.yaml…
    # 🚀 specs/one.yaml -> schemas/specs/one.ts [250ms]
    # 🚀 specs/two.yaml -> schemas/specs/two.ts [250ms]
    # 🚀 specs/three.yaml -> schemas/specs/three.ts [250ms]

    Note: if generating a single schema, --output must be a file (preferably *.ts). If using globs, --output must be a directory.

    Thanks to @sharmarajdaksh for the glob feature!

    ☁️ Reading specs from remote resource

    npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts
    
    # 🔭 Loading spec from https://petstore.swagger.io/v2/swagger.json…
    # 🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]

    Note: globbing doesn’t work for remote schemas because there is no reliable way to determine a list of files to select from a remote file system.

    Thanks to @psmyrdek for the remote spec feature!

    Using in TypeScript

    Import any top-level item from the generated spec to use it. It works best if you also alias types to save on typing:

    import { components } from './generated-schema.ts';
    
    type APIResponse = components["schemas"]["APIResponse"];

    Because OpenAPI schemas may have invalid TypeScript characters as names, the square brackets are a safe way to access every property.

    Also note that there’s a special operations interface that you can import OperationObjects by their operationId:

    import { operations } from './generated-schema.ts';
    
    type getUsersById = operations["getUsersById"];

    Even though operations isn’t present in your original schema, it’s a simple convenience and won’t disrupt any of your other types.

    Thanks to @gr2m for the operations feature!

    Outputting to stdout

    Simply omit the --output flag to return to stdout:

    npx openapi-typescript schema.yaml

    CLI Options

    Option Alias Default Description
    --output [location] -o (stdout) Where should the output file be saved?
    --auth [token] (optional) Provide an auth token to be passed along in the request (only if accessing a private schema)
    --immutable-types -it false (optional) Generates immutable types (readonly properties and readonly array)
    --additional-properties -ap false (optional) Allow arbitrary properties for all schema objects without additionalProperties: false
    --default-non-nullable false (optional) Treat schema objects with default values as non-nullable
    --prettier-config [location] -c (optional) Path to your custom Prettier configuration for output
    --raw-schema false Generate TS types from partial schema (e.g. having components.schema at the top level)
    --httpMethod -m GET (optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL
    --headersObject -h (optional) Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over --header
    --header -x (optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern

    🐢 Node

    npm i --save-dev openapi-typescript
    const fs = require("fs");
    const openapiTS = require("openapi-typescript").default;
    
    // example 1: load [object] as schema (JSON only)
    const schema = await fs.promises.readFile("spec.json", "utf8") // must be OpenAPI JSON
    const output = await openapiTS(JSON.parse(schema));
    
    // example 2: load [string] as local file (YAML or JSON; released in v4.0)
    const localPath = path.join(__dirname, 'spec.yaml'); // may be YAML or JSON format
    const output = await openapiTS(localPath);
    
    // example 3: load [string] as remote URL (YAML or JSON; released in v4.0)
    const output = await openapiTS('https://myurl.com/v1/openapi.yaml');

    The Node API may be useful if dealing with dynamically-created schemas, or you’re using within context of a larger application. Pass in either a JSON-friendly object to load a schema from memory, or a string to load a schema from a local file or remote URL (it will load the file quickly using built-in Node methods). Note that a YAML string isn’t supported in the Node.js API; either use the CLI or convert to JSON using js-yaml first.

    ⚠️ As of v4.0, openapiTS() is an async function.

    Custom Formatter

    If using the Node.js API, you can optionally pass a formatter to openapi-typescript. This is useful if you want to override the default types and substitute your own.

    For example, say your schema has the following property:

    properties:
      updated_at:
        type: string
        format: date-time

    By default, this will generate a type updated_at?: string;. But we can override this by passing a formatter to the Node API, like so:

    const types = openapiTS(mySchema, {
      formatter(node: SchemaObject) {
        if (node.format === 'date-time') {
          return "Date"; // return the TypeScript “Date” type, as a string
        }
      // for all other schema objects, let openapi-typescript decide (return undefined)
    });

    This will generate updated_at?: Date instead. Note that you will still have to do the parsing of your data yourself. But this will save you from having to also update all your types.

    Note: you don’t have to use .format—this is just an example! You can use any property on a schema object to overwrite its generated type if desired.

    🏅 Project Goals

    1. Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
    2. The generated TypeScript types must match your schema as closely as possible (i.e. don’t convert names to PascalCase or follow any TypeScript-isms; faithfully reproduce your schema as closely as possible, capitalization and all)
    3. This library is a TypeScript generator, not a schema validator.

    🤝 Contributing

    PRs are welcome! Please see our CONTRIBUTING.md guide. Opening an issue beforehand to discuss is encouraged but not required.

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Drew Powers

    💻 📖 🚇 ⚠️

    Przemek Smyrdek

    💻 📖 🤔 ⚠️

    Dan Enman

    🐛 💻

    Atle Frenvik Sveen

    💻 📖 🤔 ⚠️

    Tim de Wolf

    💻 🤔

    Tom Barton

    💻 📖 🤔 ⚠️

    Sven Nicolai Viig

    🐛 💻 ⚠️

    Sorin Davidoi

    🐛 💻 ⚠️

    Nathan Schneirov

    💻 📖 🤔 ⚠️

    Lucien Bénié

    💻 📖 🤔 ⚠️

    Boris K

    📖

    Anton

    🐛 💻 🤔 ⚠️

    Tim Shelburne

    💻 ⚠️

    Michał Miszczyszyn

    💻

    Sam K Hall

    💻 ⚠️

    Matt Jeanes

    💻

    Kristofer Giltvedt Selbekk

    💻

    Elliana May

    💻 ⚠️

    Henrik Hall

    💻 📖 ⚠️

    Gregor Martynus

    💻 ⚠️ 🐛

    Sam Mesterton-Gibbons

    💻 🐛 ⚠️

    Rendall

    💻 🐛 ⚠️

    Robert Massaioli

    💻 🐛

    Jan Kuča

    💻 ⚠️

    Thomas Valadez

    📖

    Asitha de Silva

    💻 🐛

    Mikhail Yermolayev

    🐛

    Alex Batalov

    💻 ⚠️

    Federico Bevione

    🐛 💻 ⚠️

    Daisuke Yamamoto

    💻 🐛 ⚠️

    dnalborczyk

    📖 💻 ⚠️

    FabioWanner

    🐛 💻 ⚠️

    Ash Smith

    💻 🐛 ⚠️

    Micah Halter

    💻 ⚠️ 🐛

    Yuto Yoshihara

    💻 🐛 ⚠️

    Dakshraj Sharma

    💻

    Shaosu Liu

    💻

    Vytenis

    💻

    Eric Zorn

    💻 ⚠️ 📖

    Max Belsky

    💻 🐛

    Peter Bech

    💻 🐛

    Rusty Conover

    💻

    Dave Carlson

    💻

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i openapi-typescript

    DownloadsWeekly Downloads

    94,410

    Version

    4.4.0

    License

    ISC

    Unpacked Size

    248 kB

    Total Files

    88

    Last publish

    Collaborators

    • drewpowers