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

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

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

• Basic usage
• OpenAPI object
• Client instances --name
• Argument vs. Object style --useOptions
• Enums vs. Union types --useUnionTypes
• Runtime schemas --exportSchemas
• Enum with custom names and descriptions
• Nullable props (OpenAPI v2)
• Authorization
• External references
• Canceling requests
• Custom request file

Support

• Babel support
• Axios support
• Angular support
• Node-Fetch support

Changelog

[0.24.0] - 2023-04-10

Fixed

• Upgraded dependencies
• Fixed issue with Cancelable promise
• Fixed issue with escaping reserved keywords in schema names

Added

• Added --postfixModels option