README
@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.