swag-ts

README

swag-ts

Simply provide a OpenAPI Specification and swag-ts will generate typescript types for you. You can provide json or yaml definitions on your local filesystem or a remote url.

Motivation

Why another type generator for OpenAPI (Swagger)? Well it's because I could not find a generator that only generates typescript types. Most generators also generate runtime code which I don't necessarily need. I just want to have the typescript types to use them in my frontend application.

If thats something for you, feel free to use it. If you need more functionality, feel free to open an issue or a pull request.

Installation

go install github.com/ditschedev/swag-ts@latest

Usage

Usage:
  swag-ts [flags]

Flags:
  -f, --file string     file path or url to the OpenAPI Specification
  -h, --help            help for swag-ts
  -o, --output string   output file for generated definitions (default "./types/swagger.ts")
  -v, --version         shows the version of the cli

Format

This library aims to only provide typescript type definitions from a given OpenAPI Specification. It does not provide any runtime functionality. All types are exported as interface.

For example, the following Schema:

LoginResponse:
  required:
    - token
  type: object
  properties:
    token:
      minLength: 1
      type: string
  additionalProperties: false

LoginResponseWrapper:
  required:
    - data
  type: object
  properties:
    data:
      $ref: '#/components/schemas/LoginResponse'
    message:
      type: string
      nullable: true
  additionalProperties: false

will be converted to the following typescript definitions:

export interface LoginResponse {
  token: string;
}

export interface LoginResponseWrapper {
  data: LoginResponse;
  message?: string | null;
}

Enums

Enums are converted to typescript enums. See the example below:

Car:
  required:
    - manufacturer
  type: object
  properties:
    manufacturer:
      $ref: "#/components/schemas/CarManufacturer"
CarManufacturer:
  type: string
  enum:
    - BMW
    - Mercedes
    - Audi  

will be converted to the following typescript definitions:

export interface Car {
    manufacturer: CarManufacturer;
}

export enum CarManufacturer {
    BMW = "BMW",
    Mercedes = "Mercedes",
    Audi = "Audi",
}

FormData Requests

If you have a request with multipart/form-data content type the cli will generate a type definition as well. As for most OpenAPI Specs the schema of the form data will not be added to the schemas section of the definition itself, rather than in the requestBody section of the path.

The generated type will be named after the operation id with a suffix of FormData. For converting this type to a FormData object you can use the convertToFormData function from the generated file.