swagger-typescript-api 11.1.3 → 12.0.1

package/README.md

@@ -70,11 +70,12 @@ Options:
   --type-prefix <string>        data contract name prefix (default: "")
   --type-suffix <string>        data contract name suffix (default: "")
   --clean-output                clean output folder before generate api. WARNING: May cause data loss (default: false)
-  --api-class-name <string>     name of the api class
+  --api-class-name <string>     name of the api class (default: "Api")
   --patch                       fix up small errors in the swagger source definition (default: false)
   --debug                       additional information about processes inside this tool (default: false)
   --another-array-type          generate array types as Array<Type> (by default Type[]) (default: false)
   --sort-types                  sort fields and types (default: false)
+  --extract-enums               extract all enums from inline interface\type content to typescript enum construction (default: false)
   -h, --help                    display help for command
 
 Commands:
@@ -138,9 +139,20 @@ generateApi({
   generateUnionEnums: false,
   typePrefix: '',
   typeSuffix: '',
+  enumKeyPrefix: '',
+  enumKeySuffix: '',
   addReadonly: false,
+  extractingOptions: {
+    requestBodySuffix: ["Payload", "Body", "Input"],
+    requestParamsSuffix: ["Params"],
+    responseBodySuffix: ["Data", "Result", "Output"],
+    responseErrorSuffix: ["Error", "Fail", "Fails", "ErrorData", "HttpError", "BadResponse"],
+  },
+  /** allow to generate extra files based with this extra templates, see more below */
   extraTemplates: [],
-  anotherArrayType: false, 
+  anotherArrayType: false,
+  fixInvalidTypeNamePrefix: "Type",
+  fixInvalidEnumKeyPrefix: "Value", 
   codeGenConstructs: (constructs) => ({
     ...constructs,
     RecordType: (key, value) => `MyRecord<key, value>`
@@ -157,8 +169,9 @@ generateApi({
     onCreateRoute: (routeData) => {},
     onCreateRouteName: (routeNameInfo, rawRouteInfo) => {},
     onFormatRouteName: (routeInfo, templateRouteName) => {},
-    onFormatTypeName: (typeName, rawTypeName) => {},
+    onFormatTypeName: (typeName, rawTypeName, schemaType) => {},
     onInit: (configuration) => {},
+    onPreParseSchema: (originalSchema, typeName, schemaType) => {},
     onParseSchema: (originalSchema, parsedSchema) => {},
     onPrepareConfig: (currentConfiguration) => {},
   }
@@ -239,8 +252,13 @@ with `--module-name-index 0` Api class will have one property `api`
 When we change it to `--module-name-index 1` then Api class have two properties `fruits` and `vegetables`  
 
 ### **`--module-name-first-tag`**  
-This option will group your API operations based on their first tag - mirroring how the Swagger UI groups displayed operations
+This option will group your API operations based on their first tag - mirroring how the Swagger UI groups displayed operations  
 
+### `extraTemplates` (NodeJS option)  
+type `(Record<string, any> & { name: string, path: string })[]`  
+This thing allow you to generate extra ts\js files based on extra templates (one extra template for one ts\js file)   
+[Example here](https://github.com/acacode/swagger-typescript-api/tree/next/tests/spec/extra-templates)    
+ 
 
 ## `generate-templates` command    
 This command allows you to generate source templates which using with option `--templates`
@@ -427,7 +445,7 @@ generateApi({
         },
         array: (schema, parser) => {
             const content = parser.getInlineParseContent(schema.items);
-            return parser.checkAndAddNull(schema, `(${content})[]`);
+            return parser.safeAddNullToType(schema, `(${content})[]`);
         },
     })
 })

package/index.d.ts

@@ -106,7 +106,7 @@ interface GenerateApiParamsBase {
   /**
    * default type for empty response schema (default: "void")
    */
-  defaultResponseType?: boolean;
+  defaultResponseType?: string;
   /**
    * Ability to send HttpClient instance to Api constructor
    */
@@ -136,6 +136,25 @@ interface GenerateApiParamsBase {
   primitiveTypeConstructs?: (struct: PrimitiveTypeStruct) => Partial<PrimitiveTypeStruct>;
 
   codeGenConstructs?: (struct: CodeGenConstruct) => Partial<CodeGenConstruct>;
+
+  /** extract all enums from nested types\interfaces to `enum` construction */
+  extractEnums?: boolean;
+  /** prefix string value needed to fix invalid type names (default: 'Type') */
+  fixInvalidTypeNamePrefix?: string;
+  /** prefix string value needed to fix invalid enum keys (default: 'Value') */
+  fixInvalidEnumKeyPrefix?: string;
+  /** prefix string value for enum keys */
+  enumKeyPrefix?: string;
+  /** suffix string value for enum keys */
+  enumKeySuffix?: string;
+  /** prefix string value for type names */
+  typePrefix?: string;
+  /** suffix string value for type names */
+  typeSuffix?: string;
+  /** extra configuration for extracting type names operations */
+  extractingOptions?: Partial<ExtractingOptions>;
+  /** configuration for fetching swagger schema requests */
+  requestOptions?: null | Partial<import("node-fetch").RequestInit>;
 }
 
 type CodeGenConstruct = {
@@ -212,9 +231,39 @@ interface GenerateApiParamsFromSpecLiteral extends GenerateApiParamsBase {
 
 export type GenerateApiParams = GenerateApiParamsFromPath | GenerateApiParamsFromUrl | GenerateApiParamsFromSpecLiteral;
 
+type BuildRouteParam = {
+  /** {bar} */
+  $match: string;
+  name: string;
+  required: boolean;
+  type: "string";
+  description: string;
+  schema: {
+    type: string;
+  };
+  in: "path" | "query";
+};
+
+type BuildRoutePath = {
+  /** /foo/{bar}/baz */
+  originalRoute: string;
+  /** /foo/${bar}/baz */
+  route: string;
+  pathParams: BuildRouteParam[];
+  queryParams: BuildRouteParam[];
+};
+
 export interface Hooks {
+  /** calls before parse\process route path */
+  onPreBuildRoutePath: (routePath: string) => string | void;
+  /** calls after parse\process route path */
+  onBuildRoutePath: (data: BuildRoutePath) => BuildRoutePath | void;
+  /** calls before insert path param name into string path interpolation */
+  onInsertPathParam: (paramName: string, index: number, arr: BuildRouteParam[], resultRoute: string) => string | void;
   /** calls after parse schema component */
   onCreateComponent: (component: SchemaComponent) => SchemaComponent | void;
+  /** calls before parse any kind of schema */
+  onPreParseSchema: (originalSchema: any, typeName: string, schemaType: string) => any;
   /** calls after parse any kind of schema */
   onParseSchema: (originalSchema: any, parsedSchema: any) => any | void;
   /** calls after parse route (return type: customized route (ParsedRoute), nothing change (void), false (ignore this route)) */
@@ -228,7 +277,7 @@ export interface Hooks {
   /** customize request params (path params, query params) */
   onCreateRequestParams?: (rawType: SchemaComponent["rawTypeData"]) => SchemaComponent["rawTypeData"] | void;
   /** customize name of model type */
-  onFormatTypeName?: (typeName: string, rawTypeName?: string) => string | void;
+  onFormatTypeName?: (typeName: string, rawTypeName?: string, schemaType?: "type-name" | "enum-key") => string | void;
   /** customize name of route (operationId), you can do it with using onCreateRouteName too */
   onFormatRouteName?: (routeInfo: RawRouteInfo, templateRouteName: string) => string | void;
 }
@@ -376,6 +425,17 @@ export enum SCHEMA_TYPES {
 
 type MAIN_SCHEMA_TYPES = SCHEMA_TYPES.PRIMITIVE | SCHEMA_TYPES.OBJECT | SCHEMA_TYPES.ENUM;
 
+type ExtractingOptions = {
+  requestBodySuffix: string[];
+  responseBodySuffix: string[];
+  responseErrorSuffix: string[];
+  requestParamsSuffix: 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;
+};
+
 export interface GenerateApiConfiguration {
   apiConfig: {
     baseUrl: string;
@@ -411,6 +471,8 @@ export interface GenerateApiConfiguration {
     singleHttpClient: boolean;
     typePrefix: string;
     typeSuffix: string;
+    enumKeyPrefix: string;
+    enumKeySuffix: string;
     patch: boolean;
     cleanOutput: boolean;
     debug: boolean;
@@ -420,7 +482,10 @@ export interface GenerateApiConfiguration {
     addReadonly: boolean;
     extractResponseBody: boolean;
     extractResponseError: boolean;
-    defaultResponseType: boolean;
+    extractEnums: boolean;
+    fixInvalidTypeNamePrefix: string;
+    fixInvalidEnumKeyPrefix: string;
+    defaultResponseType: string;
     toJS: boolean;
     disableThrowOnError: boolean;
     silent: boolean;
@@ -452,6 +517,7 @@ export interface GenerateApiConfiguration {
     routeNameDuplicatesMap: Map<string, string>;
     apiClassName: string;
     requestOptions?: import("node-fetch").RequestInit;
+    extractingOptions: ExtractingOptions;
   };
   modelTypes: ModelType[];
   rawModelTypes: SchemaComponent[];
@@ -466,6 +532,7 @@ export interface GenerateApiConfiguration {
       routes: ParsedRoute[];
     }[];
   };
+  requestOptions?: null | Partial<import("node-fetch").RequestInit>;
   utils: {
     formatDescription: (description: string, inline?: boolean) => string;
     internalCase: (value: string) => string;

package/index.js

@@ -37,7 +37,7 @@ const program = cli({
     {
       flags: "-n, --name <string>",
       description: "name of output typescript api file",
-      default: `${codeGenBaseConfig.apiClassName}.ts`,
+      default: codeGenBaseConfig.fileName,
     },
     {
       flags: "-t, --templates <string>",
@@ -202,6 +202,11 @@ const program = cli({
       description: "sort fields and types",
       default: codeGenBaseConfig.sortTypes,
     },
+    {
+      flags: "--extract-enums",
+      description: "extract all enums from inline interface\\type content to typescript enum construction",
+      default: codeGenBaseConfig.extractEnums,
+    },
   ],
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-typescript-api",
-  "version": "11.1.3",
+  "version": "12.0.1",
   "description": "Generate typescript/javascript api from swagger schema",
   "scripts": {
     "cli:json": "node index.js -r -d -p ./swagger-test-cli.json -n swagger-test-cli.ts",
@@ -56,7 +56,10 @@
     "test:nullableRefTest2.0": "node tests/spec/nullable-2.0/test.js",
     "test:additionalProperties2.0": "node tests/spec/additional-properties-2.0/test.js",
     "test:enums2.0": "node tests/spec/enums-2.0/test.js",
-    "test:another-query-params": "node tests/spec/another-query-params/test.js"
+    "test:another-query-params": "node tests/spec/another-query-params/test.js",
+    "test:on-insert-path-param": "node tests/spec/on-insert-path-param/test.js",
+    "test:extra-templates": "node tests/spec/extra-templates/test.js",
+    "test:extract-enums": "node tests/spec/extract-enums/test.js"
   },
   "author": "acacode",
   "license": "MIT",

package/src/code-gen-process.js

@@ -81,6 +81,7 @@ class CodeGenProcess {
       this.templates,
       this.typeName,
     );
+    this.config.componentTypeNameResolver.logger = this.logger;
   }
 
   async start() {
@@ -169,9 +170,11 @@ class CodeGenProcess {
 
     if (this.fileSystem.pathIsExist(this.config.output)) {
       if (this.config.cleanOutput) {
+        this.logger.debug(`cleaning dir ${this.config.output}`);
         this.fileSystem.cleanDir(this.config.output);
       }
     } else {
+      this.logger.debug(`path ${this.config.output} is not exist. creating dir by this path`);
       this.fileSystem.createDir(this.config.output);
     }
 
@@ -233,8 +236,9 @@ class CodeGenProcess {
         getParseContent: this.schemaParser.getParseContent,
         getComponentByRef: this.schemaComponentMap.get,
         parseSchema: this.schemaParser.parseSchema,
-        checkAndAddNull: this.schemaParser.checkAndAddNull,
-        isNeedToAddNull: this.schemaParser.isNeedToAddNull,
+        checkAndAddNull: this.schemaParser.schemaUtils.safeAddNullToType,
+        safeAddNullToType: this.schemaParser.schemaUtils.safeAddNullToType,
+        isNeedToAddNull: this.schemaParser.schemaUtils.isNullMissingInType,
         inlineExtraFormatters: this.schemaParser.schemaFormatters.inline,
         formatters: this.schemaParser.schemaFormatters.base,
         formatModelName: this.typeName.format,
@@ -397,15 +401,11 @@ class CodeGenProcess {
     if (configuration.translateToJavaScript) {
       const { sourceContent, declarationContent } = translateToJS(`${fixedFileName}${ts.Extension.Ts}`, content);
 
-      if (this.config.debug) {
-        console.info("generating output for", `${fixedFileName}${ts.Extension.Js}`);
-        console.info(sourceContent);
-      }
+      this.logger.debug("generating output for", `${fixedFileName}${ts.Extension.Js}`);
+      this.logger.debug(sourceContent);
 
-      if (this.config.debug) {
-        console.info("generating output for", `${fixedFileName}${ts.Extension.Dts}`);
-        console.info(declarationContent);
-      }
+      this.logger.debug("generating output for", `${fixedFileName}${ts.Extension.Js}`);
+      this.logger.debug(declarationContent);
 
       return {
         name: `${fixedFileName}${ts.Extension.Js}`,
@@ -417,10 +417,8 @@ class CodeGenProcess {
       };
     }
 
-    if (this.config.debug) {
-      console.info("generating output for", `${fixedFileName}${ts.Extension.Ts}`);
-      console.info(content);
-    }
+    this.logger.debug("generating output for", `${fixedFileName}${ts.Extension.Js}`);
+    this.logger.debug(content);
 
     return {
       name: `${fixedFileName}${ts.Extension.Ts}`,

package/src/configuration.js

@@ -72,6 +72,7 @@ class CodeGenConfig {
   extractRequestBody = false;
   extractResponseBody = false;
   extractResponseError = false;
+  extractEnums = false;
   fileNames = {
     dataContracts: "data-contracts",
     routeTypes: "route-types",
@@ -81,14 +82,18 @@ class CodeGenConfig {
   routeNameDuplicatesMap = new Map();
   prettierOptions = { ...CONSTANTS.PRETTIER_OPTIONS };
   hooks = {
+    onPreBuildRoutePath: (routePath) => void 0,
+    onBuildRoutePath: (routeData) => void 0,
+    onInsertPathParam: (pathParam) => void 0,
     onCreateComponent: (schema) => schema,
+    onPreParseSchema: (originalSchema, typeName, schemaType) => void 0,
     onParseSchema: (originalSchema, parsedSchema) => parsedSchema,
     onCreateRoute: (routeData) => routeData,
     onInit: (config) => config,
     onPrepareConfig: (apiConfig) => apiConfig,
     onCreateRequestParams: (rawType) => {},
     onCreateRouteName: () => {},
-    onFormatTypeName: (typeName, rawTypeName) => {},
+    onFormatTypeName: (typeName, rawTypeName, schemaType) => {},
     onFormatRouteName: (routeInfo, templateRouteName) => {},
   };
   defaultResponseType;
@@ -126,8 +131,10 @@ class CodeGenConfig {
   silent = false;
   typePrefix = "";
   typeSuffix = "";
+  enumKeyPrefix = "";
+  enumKeySuffix = "";
   patch = false;
-  componentTypeNameResolver = new ComponentTypeNameResolver([]);
+  componentTypeNameResolver = new ComponentTypeNameResolver(null, []);
   /** name of the main exported class */
   apiClassName = "Api";
   debug = false;
@@ -142,15 +149,25 @@ class CodeGenConfig {
   url = "";
   cleanOutput = false;
   spec = null;
-  fileName = "";
+  fileName = "Api.ts";
   authorizationToken = void 0;
   requestOptions = null;
 
   jsPrimitiveTypes = [];
   jsEmptyTypes = [];
+  fixInvalidTypeNamePrefix = "Type";
+  fixInvalidEnumKeyPrefix = "Value";
 
   successResponseStatusRange = [200, 299];
 
+  /** @type {ExtractingOptions} */
+  extractingOptions = {
+    requestBodySuffix: ["Payload", "Body", "Input"],
+    requestParamsSuffix: ["Params"],
+    responseBodySuffix: ["Data", "Result", "Output"],
+    responseErrorSuffix: ["Error", "Fail", "Fails", "ErrorData", "HttpError", "BadResponse"],
+  };
+
   Ts = {
     Keyword: _.cloneDeep(TsKeyword),
     CodeGenKeyword: _.cloneDeep(TsCodeGenKeyword),
@@ -235,6 +252,12 @@ class CodeGenConfig {
     TypeWithGeneric: (typeName, genericArgs) => {
       return `${typeName}${genericArgs.length ? `<${genericArgs.join(",")}>` : ""}`;
     },
+    /**
+     * [$A1, $A2, ...$AN]
+     */
+    Tuple: (values) => {
+      return `[${values.join(", ")}]`;
+    },
   };
 
   /**
@@ -273,7 +296,7 @@ class CodeGenConfig {
     },
     array: ({ items, ...schemaPart }, parser) => {
       const content = parser.getInlineParseContent(items);
-      return parser.checkAndAddNull(schemaPart, this.Ts.ArrayType(content));
+      return parser.schemaUtils.safeAddNullToType(schemaPart, this.Ts.ArrayType(content));
     },
   };
 

package/src/schema-parser/schema-formatters.js

@@ -28,10 +28,7 @@ class SchemaFormatters {
 
   base = {
     [SCHEMA_TYPES.ENUM]: (parsedSchema) => {
-      const isNumberEnum = _.some(parsedSchema.content, (content) => typeof content.key === "number");
-      const formatAsUnionType = !!(isNumberEnum || this.config.generateUnionEnums);
-
-      if (formatAsUnionType) {
+      if (this.config.generateUnionEnums) {
         return {
           ...parsedSchema,
           $content: parsedSchema.content,
@@ -61,19 +58,32 @@ class SchemaFormatters {
     },
   };
   inline = {
+    [SCHEMA_TYPES.ENUM]: (parsedSchema) => {
+      return {
+        ...parsedSchema,
+        content: parsedSchema.$ref
+          ? parsedSchema.typeName
+          : this.config.Ts.UnionType(
+              _.compact([
+                ..._.map(parsedSchema.content, ({ value }) => `${value}`),
+                parsedSchema.nullable && this.config.Ts.Keyword.Null,
+              ]),
+            ),
+      };
+    },
     [SCHEMA_TYPES.OBJECT]: (parsedSchema) => {
       if (_.isString(parsedSchema.content)) {
         return {
           ...parsedSchema,
           typeIdentifier: this.config.Ts.Keyword.Type,
-          content: this.schemaParser.checkAndAddNull(parsedSchema.content),
+          content: this.schemaParser.schemaUtils.safeAddNullToType(parsedSchema.content),
         };
       }
 
       return {
         ...parsedSchema,
         typeIdentifier: this.config.Ts.Keyword.Type,
-        content: this.schemaParser.checkAndAddNull(
+        content: this.schemaParser.schemaUtils.safeAddNullToType(
           parsedSchema,
           parsedSchema.content.length
             ? this.config.Ts.ObjectWrapper(this.formatObjectContent(parsedSchema.content))
@@ -81,19 +91,16 @@ class SchemaFormatters {
         ),
       };
     },
-    [SCHEMA_TYPES.ENUM]: (parsedSchema) => {
-      return {
-        ...parsedSchema,
-        content: parsedSchema.$ref
-          ? parsedSchema.typeName
-          : this.config.Ts.UnionType(
-              _.compact([
-                ..._.map(parsedSchema.content, ({ value }) => `${value}`),
-                parsedSchema.nullable && this.config.Ts.Keyword.Null,
-              ]),
-            ),
-      };
-    },
+  };
+
+  /**
+   * @param parsedSchema {Record<string, any>}
+   * @param formatType {"base" | "inline"}
+   */
+  formatSchema = (parsedSchema, formatType = "base") => {
+    const schemaType = _.get(parsedSchema, ["schemaType"]) || _.get(parsedSchema, ["$parsed", "schemaType"]);
+    const formatterFn = _.get(this, [formatType, schemaType]);
+    return (formatterFn && formatterFn(parsedSchema)) || parsedSchema;
   };
 
   formatDescription = (description, inline) => {