ESM and TypeScript rewrite of Acacode's swagger-typescript-api

API

npx swagger-typescript-api-es@latest --help

CLI

npx swagger-typescript-api-es@latest -u https://petstore.swagger.io/v2/swagger.json -o ./src/api

CLI Options

Option	Alias	Description	Default
--u <url>		Path/url to swagger scheme	-
--o <output>		Output path of typescript api file	"./"
--n <name>		Name of output typescript api file	"Api.ts"
--t <templates>		Path to folder containing templates	-
--d <default-as-success>		Use "default" response status code as success response too	false
--r <responses>		Generate additional information about request responses also add typings for bad responses	false
--union-enums		Generate all "enum" types as union types (T1 | T2 | TN)	false
--add-readonly		Generate readonly properties	false
--route-types		Generate type definitions for API routes	false
--noClient		Do not generate an API class	false
--enum-names-as-values		Use values in "x-enumNames" as enum values (not only as keys)	false
--extract-request-params		Extract request params to data contract (Also combine path params and query params into one object)	false
--extract-request-body		Extract request body type to data contract	false
--extract-response-body		Extract response body type to data contract	false
--extract-response-error		Extract response error type to data contract	false
--extract-enums		Extract all enums from inline interface/type content to typescript enum construction	false
--modular		Generate separated files for http client, data contracts, and routes	false
--js		Generate js api module with declaration file	false
--module-name-index		Determines which path index should be used for routes separation (example: GET:/fruits/getFruit -> index:0 -> moduleName -> fruits)	0
--module-name-first-tag		Splits routes based on the first tag	false
--disableStrictSSL		Disable strict SSL	false
--disableProxy		Disable proxy	false
--httpClientType		HTTP client type	"fetch"
--unwrap-response-data		Unwrap the data item from the response	false
--disable-throw-on-error		Do not throw an error when response.ok is not true	false
--single-http-client		Ability to send HttpClient instance to Api constructor	false
--silent		Output only errors to console	false
--default-response		Default type for empty response schema	"void"
--type-prefix		Data contract name prefix	""
--type-suffix		Data contract name suffix	""
--clean-output		Clean output folder before generate api. WARNING: May cause data loss	false
--api-class-name		Name of the api class	"Api"
--patch		Fix up small errors in the swagger source definition	false
--debug		Additional information about processes inside this tool	false
--another-array-type		Generate array types as Array<Type> (by default Type[])	false
--sort-types		Sort fields and types	false
--sort-routes		Sort routes in alphabetical order	false
--custom-config		Custom config: primitiveTypeConstructs, hooks, ...	""

Install

npm i swagger-typescript-api-es@latest --save-dev

• Create a file swagger-typescript-api.config.ts in the root of the project

import { defaultConfig } from 'swagger-typescript-api-es';

export default defaultConfig({
  name: 'api-axios.ts',
  output: './src/apis/axios-gentype',
  url: 'http://localhost:5002/api-json',
  httpClientType: 'axios',
});

Add skills

npx skills add hunghg255/swagger-typescript-api-es

Options

// Options
interface IOptions {
  /**
   *  name of output typescript api file (default: "Api.ts")
   */
  name: string;
  /**
   * output path of typescript api file (default: "./")
   */
  output: string;
  /**
   * path/url to swagger scheme
   */
  url: string;
  input?: string;
  spec?: {
    swagger?: '2.0' | '3.0';
    info?: {
      version?: string;
      title?: string;
    };
  };
  templates?: string;
  httpClientType?: 'axios' | 'fetch';
  defaultResponseAsSuccess?: boolean;
  generateClient?: boolean;
  generateRouteTypes?: boolean;
  generateResponses?: boolean;
  toJS?: boolean;
  extractRequestParams?: boolean;
  extractRequestBody?: boolean;
  extractEnums?: boolean;
  unwrapResponseData?: boolean;
  /**
   * By default oxfmtOptrions config is load from your project
   */
  oxfmtOptrions?: {
    printWidth?: number;
    tabWidth?: number;
    trailingComma?: 'all' | string;
    parser?: 'typescript' | string;
  };
  singleHttpClient?: boolean;
  cleanOutput?: boolean;
  enumNamesAsValues?: boolean;
  moduleNameFirstTag?: boolean;
  generateUnionEnums?: boolean;
  typePrefix?: string;
  typeSuffix?: string;
  enumKeyPrefix?: string;
  enumKeySuffix?: string;
  addReadonly?: boolean;
  sortTypes?: boolean;
  sortRouters?: boolean;
  extractingOptions?: {
    requestBodySuffix?: string[];
    requestParamsSuffix?: string[];
    responseBodySuffix?: string[];
    responseErrorSuffix?: string[];
  };
  /** allow to generate extra files based with this extra templates, see more below */
  extraTemplates?: [];
  anotherArrayType?: boolean;
  fixInvalidTypeNamePrefix?: string;
  fixInvalidEnumKeyPrefix?: string;
  oxfmtOptrions?: Record<string, any>;
  constants?: Record<string, any>;
  templateInfos?: any;
  codeGenConstructs?: (constructs: any) => Record<string, any>;
  primitiveTypeConstructs?: (constructs: any) => Record<string, any>;
  hooks?: {
    onCreateComponent?: (component: any) => void;
    onCreateRequestParams?: (rawType: any) => void;
    onCreateRoute?: (routeData: any) => void;
    onCreateRouteName?: (routeNameInfo: any, rawRouteInfo: any) => void;
    onFormatRouteName?: (routeInfo: any, templateRouteName: any) => void;
    onFormatTypeName?: (typeName: any, rawTypeName: any, schemaType: any) => void;
    onInit?: (configuration: any) => void;
    onPreParseSchema?: (originalSchema: any, typeName: any, schemaType: any) => void;
    onParseSchema?: (originalSchema: any, parsedSchema: any) => void;
    onPrepareConfig?: (currentConfiguration: any) => void;
  };
}

• Config (file package.json)

{
  ...
  "scripts": {
    ...
    "gen-api-types": "swagger-typescript-api-es"
  },
  ...
}

📝 License

Licensed under the MIT License.