openapi-typescript-codegen

What is openapi-typescript-codegen?

The openapi-typescript-codegen npm package is a tool that generates TypeScript clients from OpenAPI specifications. It helps developers to create strongly-typed API clients, ensuring type safety and reducing the likelihood of runtime errors.

What are openapi-typescript-codegen's main functionalities?

Generate TypeScript Client

This feature allows you to generate a TypeScript client from an OpenAPI specification file. The generated client will include all the necessary types and methods to interact with the API.

const { generate } = require('openapi-typescript-codegen');

generate({
  input: './path/to/openapi.yaml',
  output: './generated',
  clientName: 'MyApiClient'
});

Custom Templates

This feature allows you to use custom templates for generating the TypeScript client. This can be useful if you need to adhere to specific coding standards or want to customize the generated code.

const { generate } = require('openapi-typescript-codegen');

generate({
  input: './path/to/openapi.yaml',
  output: './generated',
  templates: './path/to/custom/templates'
});

Generate Models Only

This feature allows you to generate only the TypeScript models from an OpenAPI specification file. This can be useful if you only need the type definitions and not the full client.

const { generate } = require('openapi-typescript-codegen');

generate({
  input: './path/to/openapi.yaml',
  output: './generated/models',
  onlyModels: true
});

Other packages similar to openapi-typescript-codegen

openapi-generator

OpenAPI Generator is a comprehensive tool that supports generating API clients, server stubs, API documentation, and configuration in various languages. Compared to openapi-typescript-codegen, it offers broader language support and more customization options.

swagger-typescript-api

swagger-typescript-api is a tool that generates TypeScript API clients from Swagger/OpenAPI definitions. It focuses on simplicity and ease of use, similar to openapi-typescript-codegen, but may offer different customization options and templates.

typescript-fetch

typescript-fetch is a generator for TypeScript clients using the Fetch API. It is part of the OpenAPI Generator project and provides a different approach to generating TypeScript clients compared to openapi-typescript-codegen, focusing on using the Fetch API for HTTP requests.

README

OpenAPI Typescript Codegen

NodeJS 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 and XHR http clients.
• Supports OpenAPI specification v2.0 and v3.0.
• Supports JSON and YAML files for input.

Known issues:

• If you use enums inside your models / definitions then those enums are now inside a namespace with the same name as your model. This is called declaration merging. However Babel 7 now support compiling of Typescript and right now they do not support namespaces.

Installation

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

Example

package.json

{
    "scripts": {
        "generate": "openapi --input ./api/openapi.json --output ./dist"
    }
}

Command line

npm install openapi-typescript-codegen -g

openapi --input ./api/openapi.json --output ./dist

NodeJS API

const OpenAPI = require('openapi-typescript-codegen');

OpenAPI.generate(
    './api/openapi.json',
    './dist'
);

Features

Argument-style vs. Object-style

There's no named parameter in JS/TS, because of that, we offer an option --useOptions to generate code in two different styles.

Argument-style:

function createUser(name: string, password: string, type?: string, address?: string) {
    // ...
}

// usage
createUser('Jack', '123456', undefined, 'NY US');

Object-style:

interface CreateUserOptions {
    name: string,
    password: string,
    type?: string
    address?: string
}

function createUser({ name, password, type, address }: CreateUserOptions) {
    // ...
}

// usage
createUser({
    name: 'Jack',
    password: '123456',
    address: 'NY US'
});

Enum with custom names and descriptions

You can use x-enum-varnames and x-enum-descriptions in your spec to generate enum with custom names and descriptions. It's not in official spec yet. But its a supported extension that can help developers use more meaningful enumerators.

{
    "EnumWithStrings": {
        "description": "This is a simple enum with strings",
        "enum": [
            0,
            1,
            2
        ],
        "x-enum-varnames": [
            "Success",
            "Warning"
            "Error"
        ],
        "x-enum-descriptions": [
            "Used when the status of something is successful",
            "Used when the status of something has a warning"
            "Used when the status of something has an error"
        ]
    }
}

Generated code:

enum EnumWithStrings {
    /*
    * Used when the status of something is successful
    */
    Success = 0,
    /*
    * Used when the status of something has a warning
    */
    Waring = 1,
    /*
    * Used when the status of something has an error
    */
    Error = 2,
}

Authorization

The OpenAPI generator supports Bearer Token authorization. In order to enable the sending of tokens in each request you can set the token using the global OpenAPI configuration:

import { OpenAPI } from './'
OpenAPI.TOKEN = 'some-bearer-token'