swagger-typescript-api 11.1.2 → 12.0.0

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

@@ -16,6 +16,7 @@ const CONTENT_KIND = {
   FORM_DATA: "FORM_DATA",
   IMAGE: "IMAGE",
   OTHER: "OTHER",
+  TEXT: "TEXT",
 };
 
 class SchemaRoutes {
@@ -27,6 +28,10 @@ class SchemaRoutes {
    * @type {SchemaParser}
    */
   schemaParser;
+  /**
+   * @type {SchemaUtils}
+   */
+  schemaUtils;
   /**
    * @type {TypeName}
    */
@@ -54,14 +59,15 @@ class SchemaRoutes {
   constructor(config, schemaParser, schemaComponentMap, logger, templates, typeName) {
     this.config = config;
     this.schemaParser = schemaParser;
+    this.schemaUtils = this.schemaParser.schemaUtils;
     this.typeName = typeName;
     this.schemaComponentMap = schemaComponentMap;
     this.logger = logger;
     this.templates = templates;
 
     this.FORM_DATA_TYPES = _.uniq([
-      this.schemaParser.getTypeAlias({ type: "string", format: "file" }),
-      this.schemaParser.getTypeAlias({ type: "string", format: "binary" }),
+      this.schemaParser.getSchemaType({ type: "string", format: "file" }),
+      this.schemaParser.getSchemaType({ type: "string", format: "binary" }),
     ]);
   }
 
@@ -86,7 +92,9 @@ class SchemaRoutes {
     );
   };
 
-  parseRouteName = (routeName) => {
+  parseRouteName = (originalRouteName) => {
+    const routeName = this.config.hooks.onPreBuildRoutePath(originalRouteName) || originalRouteName;
+
     const pathParamMatches = (routeName || "").match(
       /({(([a-zA-Z]-?_?\.?){1,})([0-9]{1,})?})|(:(([a-zA-Z]-?_?\.?){1,})([0-9]{1,})?:?)/g,
     );
@@ -103,40 +111,75 @@ class SchemaRoutes {
           this.logger.warn("wrong path param name", paramName);
         }
 
-        return [
-          ...pathParams,
-          {
-            $match: match,
-            name: _.camelCase(paramName),
-            required: true,
+        pathParams.push({
+          $match: match,
+          name: _.camelCase(paramName),
+          required: true,
+          type: "string",
+          description: "",
+          schema: {
             type: "string",
-            description: "",
-            schema: {
-              type: "string",
-            },
-            in: "path",
           },
-        ];
+          in: "path",
+        });
+
+        return pathParams;
       },
       [],
     );
 
-    const fixedRoute = _.reduce(
+    let fixedRoute = _.reduce(
       pathParams,
-      (fixedRoute, pathParam) => {
-        return _.replace(fixedRoute, pathParam.$match, `\${${pathParam.name}}`);
+      (fixedRoute, pathParam, i, arr) => {
+        const insertion = this.config.hooks.onInsertPathParam(pathParam.name, i, arr, fixedRoute) || pathParam.name;
+        return _.replace(fixedRoute, pathParam.$match, `\${${insertion}}`);
       },
       routeName || "",
     );
 
-    return {
-      originalRoute: routeName || "",
+    const queryParamMatches = fixedRoute.match(/(\{\?.*\})/g);
+    const queryParams = [];
+
+    if (queryParamMatches && queryParamMatches.length) {
+      queryParamMatches.forEach((match) => {
+        fixedRoute = fixedRoute.replace(match, "");
+      });
+
+      _.uniq(
+        queryParamMatches
+          .join(",")
+          .replace(/(\{\?)|(\})|\s/g, "")
+          .split(","),
+      ).forEach((paramName) => {
+        if (_.includes(paramName, "-")) {
+          this.logger.warn("wrong query param name", paramName);
+        }
+
+        queryParams.push({
+          $match: paramName,
+          name: _.camelCase(paramName),
+          required: true,
+          type: "string",
+          description: "",
+          schema: {
+            type: "string",
+          },
+          in: "query",
+        });
+      });
+    }
+
+    const result = {
+      originalRoute: originalRouteName || "",
       route: fixedRoute,
       pathParams,
+      queryParams,
     };
+
+    return this.config.hooks.onBuildRoutePath(result) || result;
   };
 
-  getRouteParams = (routeInfo, pathParams) => {
+  getRouteParams = (routeInfo, pathParamsFromRouteName, queryParamsFromRouteName) => {
     const { parameters } = routeInfo;
 
     const routeParams = {
@@ -149,7 +192,7 @@ class SchemaRoutes {
     };
 
     _.each(parameters, (parameter) => {
-      const refTypeInfo = this.schemaParser.getRefType(parameter);
+      const refTypeInfo = this.schemaParser.schemaUtils.getSchemaRefType(parameter);
       let routeParam = null;
 
       if (refTypeInfo && refTypeInfo.rawTypeData.in && refTypeInfo.rawTypeData) {
@@ -186,13 +229,21 @@ class SchemaRoutes {
     });
 
     // used in case when path parameters is not declared in requestInfo.parameters ("in": "path")
-    _.each(pathParams, (pathParam) => {
+    _.each(pathParamsFromRouteName, (pathParam) => {
       const alreadyExist = _.some(routeParams.path, (parameter) => parameter.name === pathParam.name);
 
       if (!alreadyExist) {
         routeParams.path.push(pathParam);
       }
     });
+    // used in case when path parameters is not declared in requestInfo.parameters ("in": "path")
+    _.each(queryParamsFromRouteName, (queryParam) => {
+      const alreadyExist = _.some(routeParams.query, (parameter) => parameter.name === queryParam.name);
+
+      if (!alreadyExist) {
+        routeParams.query.push(queryParam);
+      }
+    });
 
     return routeParams;
   };
@@ -207,7 +258,7 @@ class SchemaRoutes {
 
   getContentKind = (contentTypes) => {
     if (
-      _.includes(contentTypes, "application/json") ||
+      _.some(contentTypes, (contentType) => _.startsWith(contentType, "application/json")) ||
       _.some(contentTypes, (contentType) => _.endsWith(contentType, "+json"))
     ) {
       return CONTENT_KIND.JSON;
@@ -225,6 +276,10 @@ class SchemaRoutes {
       return CONTENT_KIND.IMAGE;
     }
 
+    if (_.some(contentTypes, (contentType) => _.startsWith(contentType, "text/"))) {
+      return CONTENT_KIND.TEXT;
+    }
+
     return CONTENT_KIND.OTHER;
   };
 
@@ -256,7 +311,7 @@ class SchemaRoutes {
   getTypeFromRequestInfo = ({ requestInfo, parsedSchemas, operationId, defaultType, typeName }) => {
     // TODO: make more flexible pick schema without content type
     const schema = this.getSchemaFromRequestType(requestInfo);
-    const refTypeInfo = this.schemaParser.getRefType(requestInfo);
+    const refTypeInfo = this.schemaParser.schemaUtils.getSchemaRefType(requestInfo);
 
     if (schema) {
       const content = this.schemaParser.getInlineParseContent(schema, typeName);
@@ -310,7 +365,7 @@ class SchemaRoutes {
             ...(requestInfo || {}),
             contentTypes: contentTypes,
             contentKind: this.getContentKind(contentTypes),
-            type: this.schemaParser.checkAndAddNull(
+            type: this.schemaParser.schemaUtils.safeAddNullToType(
               requestInfo,
               this.getTypeFromRequestInfo({
                 requestInfo,
@@ -351,7 +406,7 @@ class SchemaRoutes {
       }
       const headerTypes = Object.fromEntries(
         Object.entries(src).map(([k, v]) => {
-          return [k, this.schemaParser.getType(v)];
+          return [k, this.schemaParser.getSchemaType(v)];
         }),
       );
       const r = `headers: { ${Object.entries(headerTypes)
@@ -420,11 +475,11 @@ class SchemaRoutes {
     let typeName = null;
 
     if (this.config.extractRequestBody) {
-      typeName = this.config.componentTypeNameResolver.resolve([
-        pascalCase(`${routeName.usage} Payload`),
-        pascalCase(`${routeName.usage} Body`),
-        pascalCase(`${routeName.usage} Input`),
-      ]);
+      typeName = this.schemaUtils.resolveTypeName(
+        routeName.usage,
+        this.config.extractingOptions.requestBodySuffix,
+        this.config.extractingOptions.requestBodyNameResolver,
+      );
     }
 
     if (routeParams.formData.length) {
@@ -436,7 +491,7 @@ class SchemaRoutes {
       type = this.schemaParser.getInlineParseContent(schema, typeName);
     } else if (requestBody) {
       schema = this.getSchemaFromRequestType(requestBody);
-      type = this.schemaParser.checkAndAddNull(
+      type = this.schemaParser.schemaUtils.safeAddNullToType(
         requestBody,
         this.getTypeFromRequestInfo({
           requestInfo: requestBody,
@@ -521,7 +576,11 @@ class SchemaRoutes {
     if (fixedSchema) return fixedSchema;
 
     if (extractRequestParams) {
-      const typeName = this.config.componentTypeNameResolver.resolve([pascalCase(`${routeName.usage} Params`)]);
+      const typeName = this.schemaUtils.resolveTypeName(
+        routeName.usage,
+        this.config.extractingOptions.requestParamsSuffix,
+        this.config.extractingOptions.requestParamsNameResolver,
+      );
 
       return this.schemaComponentMap.createComponent("schemas", typeName, { ...schema });
     }
@@ -531,11 +590,11 @@ class SchemaRoutes {
 
   extractResponseBodyIfItNeeded = (routeInfo, responseBodyInfo, routeName) => {
     if (responseBodyInfo.responses.length && responseBodyInfo.success && responseBodyInfo.success.schema) {
-      const typeName = this.config.componentTypeNameResolver.resolve([
-        pascalCase(`${routeName.usage} Data`),
-        pascalCase(`${routeName.usage} Result`),
-        pascalCase(`${routeName.usage} Output`),
-      ]);
+      const typeName = this.schemaUtils.resolveTypeName(
+        routeName.usage,
+        this.config.extractingOptions.responseBodySuffix,
+        this.config.extractingOptions.responseBodyNameResolver,
+      );
 
       const idx = responseBodyInfo.responses.indexOf(responseBodyInfo.success.schema);
 
@@ -558,14 +617,11 @@ class SchemaRoutes {
 
   extractResponseErrorIfItNeeded = (routeInfo, responseBodyInfo, routeName) => {
     if (responseBodyInfo.responses.length && responseBodyInfo.error.schemas && responseBodyInfo.error.schemas.length) {
-      const typeName = this.config.componentTypeNameResolver.resolve([
-        pascalCase(`${routeName.usage} Error`),
-        pascalCase(`${routeName.usage} Fail`),
-        pascalCase(`${routeName.usage} Fails`),
-        pascalCase(`${routeName.usage} ErrorData`),
-        pascalCase(`${routeName.usage} HttpError`),
-        pascalCase(`${routeName.usage} BadResponse`),
-      ]);
+      const typeName = this.schemaUtils.resolveTypeName(
+        routeName.usage,
+        this.config.extractingOptions.responseErrorSuffix,
+        this.config.extractingOptions.responseErrorNameResolver,
+      );
 
       const errorSchemas = responseBodyInfo.error.schemas.map(this.getSchemaFromRequestType).filter(Boolean);
 
@@ -642,7 +698,11 @@ class SchemaRoutes {
       consumes,
       ...otherInfo
     } = routeInfo;
-    const { route, pathParams } = this.parseRouteName(rawRouteName);
+    const {
+      route,
+      pathParams: pathParamsFromRouteName,
+      queryParams: queryParamsFromRouteName,
+    } = this.parseRouteName(rawRouteName);
 
     const routeId = generateId();
     const firstTag = tags && tags.length > 0 ? tags[0] : null;
@@ -655,7 +715,7 @@ class SchemaRoutes {
       hasSecurity = security.length > 0;
     }
 
-    const routeParams = this.getRouteParams(routeInfo, pathParams);
+    const routeParams = this.getRouteParams(routeInfo, pathParamsFromRouteName, queryParamsFromRouteName);
 
     const pathArgs = routeParams.path.map((pathArgSchema) => ({
       name: pathArgSchema.name,
@@ -711,13 +771,13 @@ class SchemaRoutes {
     const pathType = routeParams.path.length ? this.schemaParser.getInlineParseContent(pathObjectSchema) : null;
     const headersType = routeParams.header.length ? this.schemaParser.getInlineParseContent(headersObjectSchema) : null;
 
-    const nameResolver = new SpecificArgNameResolver(pathArgsNames);
+    const nameResolver = new SpecificArgNameResolver(this.logger, pathArgsNames);
 
     const specificArgs = {
       query: queryType
         ? {
             name: nameResolver.resolve(RESERVED_QUERY_ARG_NAMES),
-            optional: this.schemaParser.parseSchema(queryObjectSchema, null).allFieldsAreOptional,
+            optional: this.schemaParser.parseSchema(queryObjectSchema).allFieldsAreOptional,
             type: queryType,
           }
         : void 0,
@@ -731,14 +791,14 @@ class SchemaRoutes {
       pathParams: pathType
         ? {
             name: nameResolver.resolve(RESERVED_PATH_ARG_NAMES),
-            optional: this.schemaParser.parseSchema(pathObjectSchema, null).allFieldsAreOptional,
+            optional: this.schemaParser.parseSchema(pathObjectSchema).allFieldsAreOptional,
             type: pathType,
           }
         : void 0,
       headers: headersType
         ? {
             name: nameResolver.resolve(RESERVED_HEADER_ARG_NAMES),
-            optional: this.schemaParser.parseSchema(headersObjectSchema, null).allFieldsAreOptional,
+            optional: this.schemaParser.parseSchema(headersObjectSchema).allFieldsAreOptional,
             type: headersType,
           }
         : void 0,

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

@@ -0,0 +1,165 @@
+const _ = require("lodash");
+const { SCHEMA_TYPES } = require("../constants");
+const { internalCase } = require("../util/internal-case");
+const { pascalCase } = require("../util/pascal-case");
+
+class SchemaUtils {
+  /**
+   * @type {CodeGenConfig}
+   */
+  config;
+  /**
+   * @type {SchemaComponentsMap}
+   */
+  schemaComponentsMap;
+
+  constructor(config, schemaComponentsMap) {
+    this.config = config;
+    this.schemaComponentsMap = schemaComponentsMap;
+  }
+
+  getRequiredProperties = (schema) => {
+    return _.uniq((schema && _.isArray(schema.required) && schema.required) || []);
+  };
+
+  isRefSchema = (schema) => {
+    return !!(schema && schema["$ref"]);
+  };
+
+  getEnumNames = (schema) => {
+    return schema["x-enumNames"] || schema["xEnumNames"] || schema["x-enumnames"] || schema["x-enum-varnames"];
+  };
+
+  getSchemaRefType = (schema) => {
+    if (!this.isRefSchema(schema)) return null;
+    return this.schemaComponentsMap.get(schema.$ref);
+  };
+
+  isPropertyRequired = (name, propertySchema, rootSchema) => {
+    if (propertySchema["x-omitempty"] === false) {
+      return true;
+    }
+
+    const isRequired = _.isBoolean(propertySchema.required)
+      ? !!propertySchema.required
+      : _.isArray(rootSchema.required)
+      ? rootSchema.required.includes(name)
+      : !!rootSchema.required;
+
+    if (this.config.convertedFromSwagger2) {
+      return typeof propertySchema.nullable === this.config.Ts.Keyword.Undefined
+        ? isRequired
+        : !propertySchema.nullable;
+    }
+    return isRequired;
+  };
+
+  isNullMissingInType = (schema, type) => {
+    const { nullable, type: schemaType } = schema || {};
+    return (
+      (nullable || !!_.get(schema, "x-nullable") || schemaType === this.config.Ts.Keyword.Null) &&
+      _.isString(type) &&
+      !type.includes(` ${this.config.Ts.Keyword.Null}`) &&
+      !type.includes(`${this.config.Ts.Keyword.Null} `)
+    );
+  };
+
+  safeAddNullToType = (schema, type) => {
+    if (this.isNullMissingInType(schema, type)) {
+      return this.config.Ts.UnionType([type, this.config.Ts.Keyword.Null]);
+    }
+    return type;
+  };
+
+  getSchemaPrimitiveType = (rawSchema) => {
+    const schema = rawSchema || {};
+
+    if (schema.type) {
+      return internalCase(schema.type);
+    }
+    if (schema.enum) {
+      const enumFieldType = typeof schema.enum[0];
+      if (enumFieldType === this.config.Ts.Keyword.Undefined) return;
+
+      return internalCase(enumFieldType);
+    }
+    if (_.keys(schema.properties).length) {
+      return SCHEMA_TYPES.OBJECT;
+    }
+    if (!!schema.items) {
+      return SCHEMA_TYPES.ARRAY;
+    }
+
+    return null;
+  };
+
+  checkAndAddRequiredKeys = (schema, resultType) => {
+    if ("$$requiredKeys" in schema && schema.$$requiredKeys.length) {
+      this.config.update({
+        internalTemplateOptions: {
+          addUtilRequiredKeysType: true,
+        },
+      });
+      return this.config.Ts.TypeWithGeneric(this.config.Ts.CodeGenKeyword.UtilRequiredKeys, [
+        resultType,
+        this.config.Ts.UnionType(schema.$$requiredKeys.map(this.config.Ts.StringValue)),
+      ]);
+    }
+
+    return resultType;
+  };
+
+  makeAddRequiredToChildSchema = (parentSchema, childSchema) => {
+    if (!childSchema) return childSchema;
+
+    const required = _.uniq([...this.getRequiredProperties(parentSchema), ...this.getRequiredProperties(childSchema)]);
+
+    const refData = this.getSchemaRefType(childSchema);
+
+    if (refData) {
+      const refObjectProperties = _.keys((refData.rawTypeData && refData.rawTypeData.properties) || {});
+      const existedRequiredKeys = refObjectProperties.filter((key) => required.includes(key));
+
+      if (!existedRequiredKeys.length) return childSchema;
+
+      return {
+        ...childSchema,
+        $$requiredKeys: existedRequiredKeys,
+      };
+    } else if (childSchema.properties) {
+      const childSchemaProperties = _.keys(childSchema.properties);
+      const existedRequiredKeys = childSchemaProperties.filter((key) => required.includes(key));
+
+      if (!existedRequiredKeys.length) return childSchema;
+
+      return {
+        required: _.uniq([...this.getRequiredProperties(childSchema), ...existedRequiredKeys]),
+        ...childSchema,
+      };
+    }
+
+    return childSchema;
+  };
+
+  filterSchemaContents = (contents, filterFn) => {
+    return _.uniq(_.filter(contents, (type) => filterFn(type)));
+  };
+
+  resolveTypeName = (typeName, suffixes, resolver) => {
+    if (resolver) {
+      return this.config.componentTypeNameResolver.resolve((reserved) => {
+        const variant = resolver(pascalCase(typeName), reserved);
+        if (variant == null) return variant;
+        return pascalCase(variant);
+      });
+    } else {
+      return this.config.componentTypeNameResolver.resolve(
+        suffixes.map((suffix) => pascalCase(`${typeName} ${suffix}`)),
+      );
+    }
+  };
+}
+
+module.exports = {
+  SchemaUtils,
+};

package/src/templates.js

@@ -164,8 +164,8 @@ class Templates {
       {
         async: false,
         ...(options || {}),
-        includeFile: (path, payload, options) => {
-          return this.renderTemplate(this.getTemplateContent(path), payload, options);
+        includeFile: (path, configuration, options) => {
+          return this.renderTemplate(this.getTemplateContent(path), configuration, options);
         },
       },
     );

package/src/type-name.js

@@ -1,5 +1,9 @@
 const _ = require("lodash");
 
+/**
+ * @typedef {"enum-key" | "type-name"} FormattingSchemaType
+ */
+
 class TypeName {
   /** @type {Map<string, string>} */
   formattedModelNamesMap = new Map();
@@ -17,12 +21,20 @@ class TypeName {
 
   /**
    * @param name
-   * @param options {{ ignorePrefix?: boolean, ignoreSuffix?: boolean }}
+   * @param options {{ type?: FormattingSchemaType }}
    * @return {string}
    */
   format = (name, options) => {
-    const typePrefix = options && options.ignorePrefix ? "" : this.config.typePrefix;
-    const typeSuffix = options && options.ignoreSuffix ? "" : this.config.typeSuffix;
+    options = options || {};
+
+    /**
+     * @type {FormattingSchemaType}
+     */
+    const schemaType = options.type || "type-name";
+
+    const typePrefix = schemaType === "enum-key" ? this.config.enumKeyPrefix : this.config.typePrefix;
+    const typeSuffix = schemaType === "enum-key" ? this.config.enumKeySuffix : this.config.typeSuffix;
+
     const hashKey = `${typePrefix}_${name}_${typeSuffix}`;
 
     if (typeof name !== "string") {
@@ -38,41 +50,48 @@ class TypeName {
       return this.formattedModelNamesMap.get(hashKey);
     }
 
-    const fixedModelName = fixModelName(name);
+    const fixedModelName = this.fixModelName(name, { type: schemaType });
 
-    const formattedModelName = _.replace(_.startCase(`${typePrefix}_${fixedModelName}_${typeSuffix}`), /\s/g, "");
-    const modelName = this.config.hooks.onFormatTypeName(formattedModelName, name) || formattedModelName;
+    const formattedName = _.replace(_.startCase(`${typePrefix}_${fixedModelName}_${typeSuffix}`), /\s/g, "");
+    const formattedResultName = this.config.hooks.onFormatTypeName(formattedName, name, schemaType) || formattedName;
 
-    this.formattedModelNamesMap.set(hashKey, modelName);
+    this.formattedModelNamesMap.set(hashKey, formattedResultName);
 
-    return modelName;
+    return formattedResultName;
   };
 
-  isValidName = isValidName;
-}
-
-const isValidName = (name) => /^([A-Za-z$_]{1,})$/g.test(name);
+  isValidName = (name) => /^([A-Za-z$_]{1,})$/g.test(name);
 
-const fixModelName = (name) => {
-  if (!isValidName(name)) {
-    if (!/^[a-zA-Z_$]/g.test(name)) {
-      name = `Type ${name}`;
+  /**
+   * @param name
+   * @param options {{ type?: FormattingSchemaType }}
+   * @return {string}
+   */
+  fixModelName = (name, options) => {
+    if (!this.isValidName(name)) {
+      if (!/^[a-zA-Z_$]/g.test(name)) {
+        const fixPrefix =
+          options && options.type === "enum-key"
+            ? this.config.fixInvalidEnumKeyPrefix
+            : this.config.fixInvalidTypeNamePrefix;
+        name = `${fixPrefix} ${name}`;
+      }
+
+      // specific replaces for TSOA 3.x
+      if (name.includes("."))
+        name = name
+          .replace(/Exclude_keyof[A-Za-z]{1,}/g, (match) => "ExcludeKeys")
+          .replace(/%22\~AND\~%22/g, "And")
+          .replace(/%22\~OR\~%22/g, "Or")
+          .replace(/(\.?%22)|\./g, "_")
+          .replace(/__+$/, "");
+
+      if (name.includes("-")) name = _.startCase(name).replace(/ /g, "");
     }
 
-    // specific replaces for TSOA 3.x
-    if (name.includes("."))
-      name = name
-        .replace(/Exclude_keyof[A-Za-z]{1,}/g, (match) => "ExcludeKeys")
-        .replace(/%22\~AND\~%22/g, "And")
-        .replace(/%22\~OR\~%22/g, "Or")
-        .replace(/(\.?%22)|\./g, "_")
-        .replace(/__+$/, "");
-
-    if (name.includes("-")) name = _.startCase(name).replace(/ /g, "");
-  }
-
-  return name;
-};
+    return name;
+  };
+}
 
 module.exports = {
   TypeName,

package/src/util/logger.js

@@ -12,7 +12,7 @@ class Logger {
     this.config = config;
   }
 
-  createLogMessage = ({ type, emojiName, messages }) => {
+  createLogMessage = ({ type, emojiName, messages, raw }) => {
     if (this.config.silent) return;
 
     const emoji = emojify(emojiName);
@@ -26,6 +26,11 @@ class Logger {
       );
     }
 
+    if (raw) {
+      console.log(...raw);
+      return;
+    }
+
     console[type](
       emoji,
       " ",
@@ -93,6 +98,19 @@ class Logger {
       emojiName: ":exclamation:",
       messages,
     });
+
+  /**
+   *
+   * @param messages {any[]}
+   * @return {void}
+   */
+  debug = (...messages) => {
+    if (!this.config.debug) return;
+
+    this.createLogMessage({
+      raw: messages,
+    });
+  };
 }
 
 module.exports = {