swagger-typescript-api 12.0.4 → 13.0.0

package/index.d.ts

@@ -1,3 +1,5 @@
+import {MonoSchemaParser} from "./src/schema-parser/mono-schema-parser";
+
 type HttpClientType = "axios" | "fetch";
 
 interface GenerateApiParamsBase {
@@ -7,7 +9,7 @@ interface GenerateApiParamsBase {
   name?: string;
 
   /**
-   * path to folder where will been located the created api module.
+   * path to folder where will be located the created api module.
    *
    * may set to `false` to skip writing content to disk. in this case,
    * you may access the `files` on the return value.
@@ -59,6 +61,11 @@ interface GenerateApiParamsBase {
    */
   sortTypes?: boolean;
 
+  /**
+   * sort routes in alphabetical order
+   */
+  sortRoutes?: boolean;
+
   /**
    * generate js api module with declaration file (default: false)
    */
@@ -168,6 +175,55 @@ interface GenerateApiParamsBase {
 
   /** configuration for fetching swagger schema requests */
   requestOptions?: null | Partial<import("node-fetch").RequestInit>;
+
+  /** ts compiler configuration object (for --to-js option) */
+  compilerTsConfig?: Record<string, any>;
+
+  /**
+   * custom ts->* translator
+   * do not use constructor args, it can break functionality of this property, just send class reference
+   *
+   * @example
+   * ```ts
+   * const { Translator } = require("swagger-typescript-api/src/translators/translator");
+   *
+   * class MyTranslator extends Translator {
+   *
+   *     translate({ fileName, fileExtension, fileContent }) {
+   *         this.codeFormatter.format()
+   *         this.config.
+   *         this.logger.
+   *
+   *         return [
+   *             {
+   *                 fileName,
+   *                 fileExtension,
+   *                 fileContent,
+   *             }
+   *         ]
+   *     }
+   * }
+   * ```
+   */
+  customTranslator?: new () => typeof import("./src/translators/translator").Translator;
+  /** fallback name for enum key resolver */
+  enumKeyResolverName?: string;
+  /** fallback name for type name resolver */
+  typeNameResolverName?: string;
+  /** fallback name for specific arg name resolver */
+  specificArgNameResolverName?: string;
+  schemaParsers?: {
+    complexOneOf?:MonoSchemaParser;
+    complexAllOf?:MonoSchemaParser;
+    complexAnyOf?:MonoSchemaParser;
+    complexNot?:MonoSchemaParser;
+    enum?:MonoSchemaParser;
+    object?:MonoSchemaParser;
+    complex?:MonoSchemaParser;
+    primitive?:MonoSchemaParser;
+    discriminator?:MonoSchemaParser;
+    array?: MonoSchemaParser;
+  }
 }
 
 type CodeGenConstruct = {
@@ -282,7 +338,10 @@ export interface Hooks {
   /** calls after parse route (return type: customized route (ParsedRoute), nothing change (void), false (ignore this route)) */
   onCreateRoute: (routeData: ParsedRoute) => ParsedRoute | void | false;
   /** Start point of work this tool (after fetching schema) */
-  onInit?: <C extends GenerateApiConfiguration["config"]>(configuration: C) => C | void;
+  onInit?: <C extends GenerateApiConfiguration["config"]>(
+    configuration: C,
+    codeGenProcess: import("./src/code-gen-process").CodeGenProcess,
+  ) => C | void;
   /** customize configuration object before sending it to ETA templates */
   onPrepareConfig?: <C extends GenerateApiConfiguration>(currentConfiguration: C) => C | void;
   /** customize route name as you need */
@@ -367,7 +426,7 @@ export interface SchemaComponent {
     };
     $parsed: ParsedSchema<SchemaTypeObjectContent | SchemaTypeEnumContent | SchemaTypePrimitiveContent>;
   };
-  componentName: string;
+  componentName: "schemas" | "paths";
   typeData: ParsedSchema<SchemaTypeObjectContent | SchemaTypeEnumContent | SchemaTypePrimitiveContent> | null;
 }
 
@@ -443,10 +502,16 @@ type ExtractingOptions = {
   responseBodySuffix: string[];
   responseErrorSuffix: string[];
   requestParamsSuffix: string[];
+  enumSuffix: string[];
+  discriminatorMappingSuffix: string[];
+  discriminatorAbstractPrefix: string[];
   requestBodyNameResolver: (name: string, reservedNames: string) => string | undefined;
   responseBodyNameResolver: (name: string, reservedNames: string) => string | undefined;
   responseErrorNameResolver: (name: string, reservedNames: string) => string | undefined;
   requestParamsNameResolver: (name: string, reservedNames: string) => string | undefined;
+  enumNameResolver: (name: string, reservedNames: string) => string | undefined;
+  discriminatorMappingNameResolver: (name: string, reservedNames: string) => string | undefined;
+  discriminatorAbstractResolver: (name: string, reservedNames: string) => string | undefined;
 };
 
 export interface GenerateApiConfiguration {
@@ -463,6 +528,18 @@ export interface GenerateApiConfiguration {
     url: string;
     spec: any;
     fileName: string;
+    templatePaths: {
+      /** `templates/base` */
+      base: string;
+      /** `templates/default` */
+      default: string;
+      /** `templates/modular` */
+      modular: string;
+      /** usage path if `--templates` option is not set */
+      original: string;
+      /** custom path to templates (`--templates`) */
+      custom: string | null;
+    };
     authorizationToken?: string;
     generateResponses: boolean;
     defaultResponseAsSuccess: boolean;
@@ -481,6 +558,7 @@ export interface GenerateApiConfiguration {
     extractRequestParams: boolean;
     unwrapResponseData: boolean;
     sortTypes: boolean;
+    sortRoutes: boolean;
     singleHttpClient: boolean;
     typePrefix: string;
     typeSuffix: string;
@@ -505,10 +583,16 @@ export interface GenerateApiConfiguration {
     hooks: Hooks;
     enumNamesAsValues: boolean;
     version: string;
+    compilerTsConfig: Record<string, any>;
+    enumKeyResolverName: string;
+    typeNameResolverName: string;
+    specificArgNameResolverName: string;
+    /** do not use constructor args, it can break functionality of this property, just send class reference */
+    customTranslator?: new (...args: never[]) => typeof import("./src/translators/translator").Translator;
     internalTemplateOptions: {
       addUtilRequiredKeysType: boolean;
     };
-    componentTypeNameResolver: typeof import("./src/util/name-resolver").ComponentTypeNameResolver;
+    componentTypeNameResolver: typeof import("./src/component-type-name-resolver").ComponentTypeNameResolver;
     fileNames: {
       dataContracts: string;
       routeTypes: string;
@@ -533,7 +617,6 @@ export interface GenerateApiConfiguration {
     extractingOptions: ExtractingOptions;
   };
   modelTypes: ModelType[];
-  rawModelTypes: SchemaComponent[];
   hasFormDataRoutes: boolean;
   hasSecurityRoutes: boolean;
   hasQueryRoutes: boolean;
@@ -569,9 +652,18 @@ export interface GenerateApiConfiguration {
   };
 }
 
+type FileInfo = {
+  /** @example myFilename */
+  fileName: string;
+  /** @example .d.ts */
+  fileExtension: string;
+  /** content of the file */
+  fileContent: string;
+};
+
 export interface GenerateApiOutput {
   configuration: GenerateApiConfiguration;
-  files: { name: string; content: string; declaration: { name: string; content: string } | null }[];
+  files: FileInfo[];
   createFile: (params: { path: string; fileName: string; content: string; withPrefix?: boolean }) => void;
   renderTemplate: (
     templateContent: string,
@@ -579,7 +671,7 @@ export interface GenerateApiOutput {
     etaOptions?: import("eta/dist/types/config").PartialConfig,
   ) => string;
   getTemplate: (params: { fileName?: string; name?: string; path?: string }) => string;
-  formatTSContent: (content: string) => string;
+  formatTSContent: (content: string) => Promise<string>;
 }
 
 export declare function generateApi(params: GenerateApiParams): Promise<GenerateApiOutput>;

package/index.js

@@ -6,245 +6,290 @@
 // License text available at https://opensource.org/licenses/MIT
 // Repository https://github.com/acacode/swagger-typescript-api
 
-const _ = require("lodash");
-const { version, name } = require("./package.json");
-const { cli } = require("./cli");
-const { generateApi, generateTemplates } = require("./src");
-const { HTTP_CLIENT } = require("./src/constants");
-const { resolve } = require("path");
-const { CodeGenConfig } = require("./src/configuration");
-const { TemplatesGenConfig } = require("./src/commands/generate-templates/configuration");
+const { version, name } = require('./package.json');
+const { cli } = require('./cli');
+const { generateApi, generateTemplates } = require('./src');
+const { HTTP_CLIENT } = require('./src/constants');
+const { resolve } = require('path');
+const { CodeGenConfig } = require('./src/configuration');
+const {
+  TemplatesGenConfig,
+} = require('./src/commands/generate-templates/configuration');
 
 const codeGenBaseConfig = new CodeGenConfig({});
 const templateGenBaseConfig = new TemplatesGenConfig({});
 
 const program = cli({
   name: name,
-  alias: "sta",
+  alias: 'sta',
   version: version,
-  description: "Generate api via swagger scheme.\nSupports OA 3.0, 2.0, JSON, yaml.",
+  description:
+    'Generate api via swagger scheme.\nSupports OA 3.0, 2.0, JSON, yaml.',
   options: [
     {
-      flags: "-p, --path <string>",
-      description: "path/url to swagger scheme",
+      flags: '-p, --path <string>',
+      description: 'path/url to swagger scheme',
       required: true,
     },
     {
-      flags: "-o, --output <string>",
-      description: "output path of typescript api file",
-      default: "./",
+      flags: '-o, --output <string>',
+      description: 'output path of typescript api file',
+      default: './',
     },
     {
-      flags: "-n, --name <string>",
-      description: "name of output typescript api file",
+      flags: '-n, --name <string>',
+      description: 'name of output typescript api file',
       default: codeGenBaseConfig.fileName,
     },
     {
-      flags: "-t, --templates <string>",
-      description: "path to folder containing templates",
+      flags: '-t, --templates <string>',
+      description: 'path to folder containing templates',
     },
     {
-      flags: "-d, --default-as-success",
+      flags: '-d, --default-as-success',
       description:
         'use "default" response status code as success response too.\n' +
         'some swagger schemas use "default" response status code as success response type by default.',
       default: codeGenBaseConfig.defaultResponseAsSuccess,
+      internal: { name: 'defaultResponseAsSuccess' },
     },
     {
-      flags: "-r, --responses",
-      description: "generate additional information about request responses\n" + "also add typings for bad responses",
+      flags: '-r, --responses',
+      description:
+        'generate additional information about request responses\n' +
+        'also add typings for bad responses',
       default: codeGenBaseConfig.generateResponses,
+      internal: { name: 'generateResponses' },
     },
     {
-      flags: "--union-enums",
+      flags: '--union-enums',
       description: 'generate all "enum" types as union types (T1 | T2 | TN)',
       default: codeGenBaseConfig.generateUnionEnums,
+      internal: { name: 'generateUnionEnums' },
     },
     {
-      flags: "--add-readonly",
-      description: "generate readonly properties",
+      flags: '--add-readonly',
+      description: 'generate readonly properties',
       default: codeGenBaseConfig.addReadonly,
     },
     {
-      flags: "--route-types",
-      description: "generate type definitions for API routes",
+      flags: '--route-types',
+      description: 'generate type definitions for API routes',
       default: codeGenBaseConfig.generateRouteTypes,
+      internal: { name: 'generateRouteTypes' },
     },
     {
-      flags: "--no-client",
-      description: "do not generate an API class",
+      flags: '--no-client',
+      description: 'do not generate an API class',
       default: codeGenBaseConfig.generateClient,
     },
     {
-      flags: "--enum-names-as-values",
-      description: "use values in 'x-enumNames' as enum values (not only as keys)",
+      flags: '--enum-names-as-values',
+      description:
+        "use values in 'x-enumNames' as enum values (not only as keys)",
       default: codeGenBaseConfig.enumNamesAsValues,
     },
     {
-      flags: "--extract-request-params",
+      flags: '--extract-request-params',
       description:
-        "extract request params to data contract (Also combine path params and query params into one object)",
+        'extract request params to data contract (Also combine path params and query params into one object)',
       default: codeGenBaseConfig.extractRequestParams,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--extract-request-body",
-      description: "extract request body type to data contract",
+      flags: '--extract-request-body',
+      description: 'extract request body type to data contract',
       default: codeGenBaseConfig.extractRequestBody,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--extract-response-body",
-      description: "extract response body type to data contract",
+      flags: '--extract-response-body',
+      description: 'extract response body type to data contract',
       default: codeGenBaseConfig.extractResponseBody,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--extract-response-error",
-      description: "extract response error type to data contract",
+      flags: '--extract-response-error',
+      description: 'extract response error type to data contract',
       default: codeGenBaseConfig.extractResponseError,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--modular",
-      description: "generate separated files for http client, data contracts, and routes",
+      flags: '--modular',
+      description:
+        'generate separated files for http client, data contracts, and routes',
       default: codeGenBaseConfig.modular,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--js",
-      description: "generate js api module with declaration file",
+      flags: '--js',
+      description: 'generate js api module with declaration file',
       default: codeGenBaseConfig.toJS,
+      internal: { formatter: Boolean, name: 'toJS' },
     },
     {
-      flags: "--module-name-index <number>",
+      flags: '--module-name-index <number>',
       description:
-        "determines which path index should be used for routes separation (example: GET:/fruites/getFruit -> index:0 -> moduleName -> fruites)",
+        'determines which path index should be used for routes separation (example: GET:/fruites/getFruit -> index:0 -> moduleName -> fruites)',
       default: codeGenBaseConfig.moduleNameIndex,
+      internal: { formatter: (moduleNameIndex) => +moduleNameIndex || 0 },
     },
     {
-      flags: "--module-name-first-tag",
-      description: "splits routes based on the first tag",
+      flags: '--module-name-first-tag',
+      description: 'splits routes based on the first tag',
       default: codeGenBaseConfig.moduleNameFirstTag,
     },
     {
-      flags: "--disableStrictSSL",
-      description: "disabled strict SSL",
+      flags: '--disableStrictSSL',
+      description: 'disabled strict SSL',
       default: codeGenBaseConfig.disableStrictSSL,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--disableProxy",
-      description: "disabled proxy",
+      flags: '--disableProxy',
+      description: 'disabled proxy',
       default: codeGenBaseConfig.disableProxy,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--axios",
-      description: "generate axios http client",
-      default: codeGenBaseConfig.httpClientType === "axios",
+      flags: '--axios',
+      description: 'generate axios http client',
+      default: codeGenBaseConfig.httpClientType === HTTP_CLIENT.AXIOS,
     },
     {
-      flags: "--unwrap-response-data",
-      description: "unwrap the data item from the response",
+      flags: '--unwrap-response-data',
+      description: 'unwrap the data item from the response',
       default: codeGenBaseConfig.unwrapResponseData,
     },
     {
-      flags: "--disable-throw-on-error",
-      description: "Do not throw an error when response.ok is not true",
+      flags: '--disable-throw-on-error',
+      description: 'Do not throw an error when response.ok is not true',
       default: codeGenBaseConfig.disableThrowOnError,
     },
     {
-      flags: "--single-http-client",
-      description: "Ability to send HttpClient instance to Api constructor",
+      flags: '--single-http-client',
+      description: 'Ability to send HttpClient instance to Api constructor',
       default: codeGenBaseConfig.singleHttpClient,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--silent",
-      description: "Output only errors to console",
+      flags: '--silent',
+      description: 'Output only errors to console',
       default: codeGenBaseConfig.silent,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--default-response <type>",
-      description: "default type for empty response schema",
+      flags: '--default-response <type>',
+      description: 'default type for empty response schema',
       default: codeGenBaseConfig.defaultResponseType,
+      internal: { name: 'defaultResponseType' },
     },
     {
-      flags: "--type-prefix <string>",
-      description: "data contract name prefix",
+      flags: '--type-prefix <string>',
+      description: 'data contract name prefix',
       default: codeGenBaseConfig.typePrefix,
     },
     {
-      flags: "--type-suffix <string>",
-      description: "data contract name suffix",
+      flags: '--type-suffix <string>',
+      description: 'data contract name suffix',
       default: codeGenBaseConfig.typeSuffix,
     },
     {
-      flags: "--clean-output",
-      description: "clean output folder before generate api. WARNING: May cause data loss",
+      flags: '--clean-output',
+      description:
+        'clean output folder before generate api. WARNING: May cause data loss',
       default: codeGenBaseConfig.cleanOutput,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--api-class-name <string>",
-      description: "name of the api class",
+      flags: '--api-class-name <string>',
+      description: 'name of the api class',
       default: codeGenBaseConfig.apiClassName,
     },
     {
-      flags: "--patch",
-      description: "fix up small errors in the swagger source definition",
+      flags: '--patch',
+      description: 'fix up small errors in the swagger source definition',
       default: codeGenBaseConfig.patch,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--debug",
-      description: "additional information about processes inside this tool",
+      flags: '--debug',
+      description: 'additional information about processes inside this tool',
       default: codeGenBaseConfig.debug,
     },
     {
-      flags: "--another-array-type",
-      description: "generate array types as Array<Type> (by default Type[])",
+      flags: '--another-array-type',
+      description: 'generate array types as Array<Type> (by default Type[])',
       default: codeGenBaseConfig.anotherArrayType,
     },
     {
-      flags: "--sort-types",
-      description: "sort fields and types",
+      flags: '--sort-types',
+      description: 'sort fields and types',
       default: codeGenBaseConfig.sortTypes,
     },
     {
-      flags: "--extract-enums",
-      description: "extract all enums from inline interface\\type content to typescript enum construction",
+      flags: '--extract-enums',
+      description:
+        'extract all enums from inline interface\\type content to typescript enum construction',
       default: codeGenBaseConfig.extractEnums,
     },
+    {
+      flags: '--sort-routes',
+      description: 'sort routes in alphabetical order',
+      default: codeGenBaseConfig.sortRoutes,
+    },
+    {
+      flags: '--custom-config <string>',
+      description: 'custom config: primitiveTypeConstructs, hooks, ... ',
+      default: '',
+    },
   ],
 });
 
 program.addCommand({
-  name: "generate-templates",
+  name: 'generate-templates',
   description: `Generate ".ejs" templates needed for generate api`,
   options: [
     {
-      flags: "-o, --output <string>",
-      description: "output path of generated templates",
+      flags: '-o, --output <string>',
+      description: 'output path of generated templates',
       default: templateGenBaseConfig.output,
     },
     {
-      flags: "-m, --modular",
-      description: "generate templates needed to separate files for http client, data contracts, and routes",
+      flags: '-m, --modular',
+      description:
+        'generate templates needed to separate files for http client, data contracts, and routes',
       default: templateGenBaseConfig.modular,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--http-client <string>",
-      description: `http client type (possible values: ${Object.values(HTTP_CLIENT)
+      flags: '--http-client <string>',
+      description: `http client type (possible values: ${Object.values(
+        HTTP_CLIENT,
+      )
         .map((v) => `"${v}"`)
-        .join(", ")})`,
+        .join(', ')})`,
       default: templateGenBaseConfig.httpClientType,
+      internal: { name: 'httpClientType' },
     },
     {
-      flags: "-c, --clean-output",
-      description: "clean output folder before generate template. WARNING: May cause data loss",
+      flags: '-c, --clean-output',
+      description:
+        'clean output folder before generate template. WARNING: May cause data loss',
       default: templateGenBaseConfig.cleanOutput,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "-r, --rewrite",
-      description: "rewrite content in existing templates",
+      flags: '-r, --rewrite',
+      description: 'rewrite content in existing templates',
       default: templateGenBaseConfig.rewrite,
+      internal: { formatter: Boolean },
     },
     {
-      flags: "--silent",
-      description: "Output only errors to console",
+      flags: '--silent',
+      description: 'Output only errors to console',
       default: templateGenBaseConfig.silent,
+      internal: { formatter: Boolean },
     },
   ],
 });
@@ -252,59 +297,36 @@ program.addCommand({
 const main = async () => {
   const { command, options } = await program.execute({ args: process.argv });
 
+  let customConfig = null;
+
+  if (options.customConfig) {
+    try {
+      const customConfigPath = resolve(process.cwd(), options.customConfig);
+      console.log(`✨ found custom config at: ${customConfigPath}`);
+      customConfig = require(customConfigPath);
+    } catch (e) {
+      /* empty */
+    }
+  }
+
   try {
     switch (command) {
       case null: {
         await generateApi({
+          ...options,
           name: options.name,
           url: options.path,
           generateRouteTypes: options.routeTypes,
           generateClient: !!(options.axios || options.client),
           httpClientType: options.axios ? HTTP_CLIENT.AXIOS : HTTP_CLIENT.FETCH,
-          defaultResponseAsSuccess: options.defaultAsSuccess,
-          defaultResponseType: options.defaultResponse,
-          unwrapResponseData: options.unwrapResponseData,
-          disableThrowOnError: options.disableThrowOnError,
-          sortTypes: options.sortTypes,
-          generateUnionEnums: options.unionEnums,
-          addReadonly: options.addReadonly,
-          generateResponses: options.responses,
-          extractRequestParams: !!options.extractRequestParams,
-          extractRequestBody: !!options.extractRequestBody,
-          extractResponseBody: !!options.extractResponseBody,
-          extractResponseError: !!options.extractResponseError,
           input: resolve(process.cwd(), options.path),
-          output: resolve(process.cwd(), options.output || "."),
-          templates: options.templates,
-          modular: !!options.modular,
-          toJS: !!options.js,
-          enumNamesAsValues: options.enumNamesAsValues,
-          moduleNameIndex: +(options.moduleNameIndex || 0),
-          moduleNameFirstTag: options.moduleNameFirstTag,
-          disableStrictSSL: !!options.disableStrictSSL,
-          disableProxy: !!options.disableProxy,
-          singleHttpClient: !!options.singleHttpClient,
-          cleanOutput: !!options.cleanOutput,
-          silent: !!options.silent,
-          typePrefix: options.typePrefix,
-          typeSuffix: options.typeSuffix,
-          patch: !!options.patch,
-          apiClassName: options.apiClassName,
-          debug: options.debug,
-          anotherArrayType: options.anotherArrayType,
-          extractEnums: options.extractEnums,
+          output: resolve(process.cwd(), options.output || '.'),
+          ...customConfig,
         });
         break;
       }
-      case "generate-templates": {
-        await generateTemplates({
-          cleanOutput: options.cleanOutput,
-          output: options.output,
-          httpClientType: options.httpClient,
-          modular: options.modular,
-          silent: options.silent,
-          rewrite: options.rewrite,
-        });
+      case 'generate-templates': {
+        await generateTemplates(options);
         break;
       }
       default: {