@simplesmiler/taxios-generate

Generate API typings for Taxios from Swagger/OpenAPI.

Generate

taxios-generate [options] <input-file-or-url>

Options:
  -o, --out FILE                    Write into this file
  -e, --export NAME                 Export generated definition under this name
      --skip-validation             Skip strict schema validation
      --named-enums                 [0.2.4+] Generate named enums instead of union types when possible
      --skip-additional-properties  [0.2.5+] Skip generating`[k: string]: unknown` for objects, unless explicitly asked
      --sort-fields                 [0.2.10+] Sort fields in interfaces instead of keeping the order from source

Example

Swagger: https://petstore.swagger.io/

taxios-generate -o PetStore.ts -e PetStore https://petstore.swagger.io/v2/swagger.json

Result: PetStore.ts

Use

import axios from 'axios';
import { Taxios } from '@simplesmiler/taxios';
import { PetStore } from './PetStore';

const taxios = new Taxios<PetStore>(axios.create({ baseURL: 'https://petstore.swagger.io/v2' }));
const pet = await taxios.get('/pet/{petId}', { params: { petId: 1 } });

See @simplesmiler/taxios package for details.

[0.2.4+] Union types and Named enums

WARNING: The following only applies to "standalone" enums. Inline enums can only be expressed as inline union types.

Look at the following OpenAPI snippet:

components:
  schemas:
    PetStatus:
      enum: [Placed, Approved, Delivered]

Prior to 0.2.4 taxios-generate would generate a union type:

export type OrderStatus = 'Placed' | 'Approved' | 'Delivered';

Since 0.2.4 you can use --named-enums option to generate a named enum instead:

export enum OrderStatus {
  Placed = 'Placed',
  Approved = 'Approved',
  Delivered = 'Delivered',
}

By default, enum names will be the same as values, assuming they are valid identifiers.

Names can also be given explicitly using x-enumNames. This is useful for numeric enums:

components:
  schemas:
    StatusCode:
      enum: [200, 400]
      x-enumNames: [Ok, BadRequest]

If no valid names are available, taxios-generate will fallback to generating a union type.

[0.2.5+] Additional properties

Look at the following OpenAPI snippet:

components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string

Prior to 0.2.5 taxios-generate would generate an interface with explicitly allowed additional properties:

export interface User {
  name?: string;
  [k: string]: unknown;
}

Since 0.2.5 you can use --skip-additional-properties option to generate an interface without then:

export interface User {
  name?: string;
}

This option treats unspecified value of OpenAPI additionalProperties field as false.

If additionalProperties is explicitly given as true, then [k: string]: unknown will still be added.

components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
      additionalProperties: true

[0.2.10+] Sort fields

Look at the following OpenAPI snippet:

components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
      required:
        - name
        - email
      additionalProperties: false

Prior to 0.2.10 fields in generated interface would always be in the same order as in the source:

export interface User {
  name: string;
  email: string;
}

Since 0.2.10 you can use --sort-fields option to enforce the alphabetical order of fields:

export interface User {
  email: string;
  name: string;
}

This option is useful if you want to minimize merge conflicts, and do have not control over the source OpenAPI document.