Release 1.10.0 (#62)

* Custom template (#60)

* feat: allow to provide custom templates

* internal: add manual test script for custom templates option

* feat: resolving paths to templates

* internal: adjust test for custom templates

Co-authored-by: Volkov Sergey <[email protected]>
Co-authored-by: Filimonov Andrey <[email protected]>

* [Feature] `--union-enums` CLI option (#61)

* feat: add --union-enums cli option which generate all enums as union types

* docs: update README, CHANGELOG

* chore(fix): manual test for union enums option

* docs: update CHANGELOG; bump: up version to 1.10.0

Co-authored-by: Filimonov Andrey <[email protected]>

Author: js2me

CHANGELOG.md

@@ -1,5 +1,26 @@
 # next release  
 
+
+# 1.10.0  
+
+Features:  
+- `--templates` CLI option. [[feature request]](https://github.com/acacode/swagger-typescript-api/issues/54)  
+  Provide custom `mustache` templates folder which allows to generate custom code (models, Api class, routes)  
+- `--union-enums` CLI option. [[feature request]](https://github.com/acacode/swagger-typescript-api/issues/58)  
+  Allows to generate all enums as union types.  
+  For example, schema part:  
+  ```
+  "StringEnum": {
+    "enum": ["String1", "String2", "String3", "String4"],
+    "type": "string"
+  }
+  ```  
+  will be converted into:
+      ```
+export type StringEnum = "String1" | "String2" | "String3" | "String4";
+      ```  
+  
+
 # 1.8.4  
 
 Fixes:  

README.md

@@ -34,11 +34,13 @@ Options:
   -p, --path <path>         path/url to swagger scheme
   -o, --output <output>     output path of typescript api file (default: "./")
   -n, --name <name>         name of output typescript api file (default: "Api.ts")
+  -t, --templates <path>    path to folder containing templates (default: "./src/templates")
   -d, --default-as-success  use "default" response status code as success response too.
                             some swagger schemas use "default" response status code
                             as success response type by default. (default: false)
   -r, --responses           generate additional information about request responses  
                             also add typings for bad responses  
+  --union-enums             generate all "enum" types as union types (T1 | T2 | TN) (default: false)
   --route-types             generate type definitions for API routes (default: false)
   --no-client               do not generate an API class
   -h, --help                output usage information

index.d.ts

@@ -1,6 +1,4 @@
-
 interface GenerateApiParams {
-
   /**
    * path to swagger schema
    */
@@ -20,7 +18,12 @@ interface GenerateApiParams {
    * path to folder where will been located the created api module
    */
   output?: string;
-  
+
+  /**
+   * path to folder containing templates (default: ./scr/templates)
+   */
+  templates?: string;
+
   /**
    * generate type definitions for API routes (default: false)
    */
@@ -32,7 +35,7 @@ interface GenerateApiParams {
   generateClient?: boolean;
 
   /**
-   * use "default" response status code as success response too.  
+   * use "default" response status code as success response too.
    * some swagger schemas use "default" response status code as success response type by default.
    */
   defaultResponseAsSuccess?: boolean;
@@ -44,5 +47,5 @@ interface GenerateApiParams {
   generateResponses?: boolean;
 }
 
-export declare function generateApi(params: Omit<GenerateApiParams, "url">): Promise<string>
-export declare function generateApi(params: Omit<GenerateApiParams, "input">): Promise<string>
+export declare function generateApi(params: Omit<GenerateApiParams, "url">): Promise<string>;
+export declare function generateApi(params: Omit<GenerateApiParams, "input">): Promise<string>;

index.js

@@ -6,51 +6,47 @@
 // License text available at https://opensource.org/licenses/MIT
 // Repository https://github.com/acacode/swagger-typescript-api
 
-const program = require('commander');
-const { resolve } = require('path');
-const { generateApi } = require('./src');
-const { version } = require('./package.json');
+const program = require("commander");
+const { resolve } = require("path");
+const { generateApi } = require("./src");
+const { version } = require("./package.json");
 
 program
-  .version(version, '-v, --version', 'output the current version')
+  .version(version, "-v, --version", "output the current version")
   .description("Generate api via swagger scheme.\nSupports OA 3.0, 2.0, JSON, yaml.")
-  .requiredOption('-p, --path <path>', 'path/url to swagger scheme')
-  .option('-o, --output <output>', 'output path of typescript api file', './')
-  .option('-n, --name <name>', 'name of output typescript api file', 'Api.ts')
+  .requiredOption("-p, --path <path>", "path/url to swagger scheme")
+  .option("-o, --output <output>", "output path of typescript api file", "./")
+  .option("-n, --name <name>", "name of output typescript api file", "Api.ts")
+  .option("-t, --templates <path>", "path to folder containing templates")
   .option(
-    '-d, --default-as-success',
+    "-d, --default-as-success",
     'use "default" response status code as success response too.\n' +
-    'some swagger schemas use "default" response status code as success response type by default.',
-    false
+      'some swagger schemas use "default" response status code as success response type by default.',
+    false,
   )
   .option(
-    '-r, --responses',
-    'generate additional information about request responses\n' +
-    'also add typings for bad responses',
+    "-r, --responses",
+    "generate additional information about request responses\n" +
+      "also add typings for bad responses",
     false,
   )
-  .option('--route-types', 'generate type definitions for API routes', false)
-  .option('--no-client', 'do not generate an API class', false);
- 
+  .option("--union-enums", 'generate all "enum" types as union types (T1 | T2 | TN)', false)
+  .option("--route-types", "generate type definitions for API routes", false)
+  .option("--no-client", "do not generate an API class", false);
+
 program.parse(process.argv);
 
-const {
-  path,
-  output,
-  name,
-  routeTypes,
-  client,
-  defaultAsSuccess,
-  responses,
-} = program;
+const { path, output, name, templates, unionEnums, routeTypes, client, defaultAsSuccess, responses } = program;
 
 generateApi({
   name,
   url: path,
   generateRouteTypes: routeTypes,
   generateClient: client,
   defaultResponseAsSuccess: defaultAsSuccess,
+  generateUnionEnums: unionEnums,
   generateResponses: responses,
   input: resolve(process.cwd(), path),
-  output: resolve(process.cwd(), output || '.')
-})
+  output: resolve(process.cwd(), output || "."),
+  templates: resolve(templates ? process.cwd() : __dirname, templates || "./src/templates"),
+});

package-lock.json

@@ -1,21 +1,23 @@
 {
   "name": "swagger-typescript-api",
-  "version": "1.8.4",
+  "version": "1.10.0",
   "description": "Create typescript api module from swagger schema",
   "scripts": {
     "cli:json": "node index.js -r -d -p ./swagger-test-cli.json -n swagger-test-cli.ts",
     "cli:yaml": "node index.js -r -d -p ./swagger-test-cli.yaml -n swagger-test-cli.ts",
-    "cli:debug:json": "node  --nolazy --inspect-brk=9229 index.js -p ./swagger-test-cli.json -n swagger-test-cli.ts",
+    "cli:debug:json": "node  --nolazy --inspect-brk=9229 index.js -p ./swagger-test-cli.json -n swagger-test-cli.ts --union-enums",
     "cli:debug:yaml": "node  --nolazy --inspect-brk=9229 index.js -p ./swagger-test-cli.yaml -n swagger-test-cli.ts",
     "cli:help": "node index.js -h",
-    "test:all": "npm-run-all generate validate test:routeTypes test:noClient test:defaultAsSuccess test:responses --continue-on-error",
+    "test:all": "npm-run-all generate validate test:routeTypes test:noClient test:defaultAsSuccess test:responses test:templates test:unionEnums --continue-on-error",
     "generate": "node tests/generate.js",
     "generate:debug": "node --nolazy --inspect-brk=9229 tests/generate.js",
     "validate": "node tests/validate.js",
     "validate:debug": "node --nolazy --inspect-brk=9229 tests/validate.js",
     "test:routeTypes": "node tests/spec/routeTypes/test.js",
     "test:noClient": "node tests/spec/noClient/test.js",
     "test:defaultAsSuccess": "node tests/spec/defaultAsSuccess/test.js",
+    "test:templates": "node tests/spec/templates/test.js",
+    "test:unionEnums": "node tests/spec/unionEnums/test.js",
     "test:responses": "node tests/spec/responses/test.js"
   },
   "author": "acacode",

package.json

@@ -1,4 +1,6 @@
 const config = {
+  /** CLI flag */
+  templates: "./templates",
   /** CLI flag */
   generateResponses: false,
   /** CLI flag */
@@ -7,6 +9,8 @@ const config = {
   generateRouteTypes: false,
   /** CLI flag */
   generateClient: true,
+  /** CLI flag */
+  generateUnionEnums: false,
   /** parsed swagger schema from getSwaggerObject() */
 
   /** parsed swagger schema ref */

src/config.js

@@ -2,21 +2,15 @@ const _ = require("lodash");
 const fs = require("fs");
 const { resolve } = require("path");
 
-const getFileContent = path =>
-  fs.readFileSync(path, { encoding: 'UTF-8' })
+const getFileContent = (path) => fs.readFileSync(path, { encoding: "UTF-8" });
 
-const pathIsExist = path =>
-  path && fs.existsSync(path)
+const pathIsExist = (path) => path && fs.existsSync(path);
 
 const createFile = (pathTo, fileName, content) =>
-  fs.writeFileSync(resolve(__dirname, pathTo, `./${fileName}`), content, _.noop)
-
-const getTemplate = templateName =>
-  getFileContent(resolve(__dirname, `./templates/${templateName}.mustache`))                       
+  fs.writeFileSync(resolve(__dirname, pathTo, `./${fileName}`), content, _.noop);
 
 module.exports = {
-  getTemplate,
   createFile,
   pathIsExist,
   getFileContent,
-}
+};

src/files.js

@@ -9,14 +9,16 @@
 const mustache = require("mustache");
 const prettier = require("prettier");
 const _ = require("lodash");
+const { resolve } = require("path");
 const { parseSchemas } = require("./schema");
 const { parseRoutes, groupRoutes } = require("./routes");
 const { createApiConfig } = require("./apiConfig");
 const { getModelType } = require("./modelTypes");
 const { getSwaggerObject, fixSwaggerScheme } = require("./swagger");
 const { createComponentsMap, filterComponentsMap } = require("./components");
-const { getTemplate, createFile, pathIsExist } = require("./files");
+const { createFile, pathIsExist } = require("./files");
 const { addToConfig, config } = require("./config");
+const { getTemplates } = require("./templates");
 
 mustache.escape = (value) => value;
 
@@ -33,20 +35,26 @@ module.exports = {
     output,
     url,
     name,
+    templates = resolve(__dirname, config.templates),
     generateResponses = config.generateResponses,
     defaultResponseAsSuccess = config.defaultResponseAsSuccess,
     generateRouteTypes = config.generateRouteTypes,
     generateClient = config.generateClient,
+    generateUnionEnums = config.generateUnionEnums,
   }) =>
     new Promise((resolve, reject) => {
       addToConfig({
         defaultResponseAsSuccess,
         generateRouteTypes,
         generateClient,
         generateResponses,
+        templates,
+        generateUnionEnums,
       });
       getSwaggerObject(input, url)
         .then(({ usageSchema, originalSchema }) => {
+          const { apiTemplate, clientTemplate, routeTypesTemplate } = getTemplates();
+
           console.log("☄️  start generating your typescript api");
 
           fixSwaggerScheme(usageSchema, originalSchema);
@@ -58,10 +66,6 @@ module.exports = {
 
           const { info, paths, servers, components } = usageSchema;
 
-          const apiTemplate = getTemplate("api");
-          const clientTemplate = getTemplate("client");
-          const routeTypesTemplate = getTemplate("route-types");
-
           const componentsMap = createComponentsMap(components);
           const schemasMap = filterComponentsMap(componentsMap, "schemas");
 

src/index.js

@@ -1,22 +1,27 @@
-const _ = require('lodash');
+const _ = require("lodash");
 const { formatters } = require("./typeFormatters");
 const { checkAndRenameModelName } = require("./modelNames");
-const { formatDescription } = require("./common")
-const { getTypeData } = require('./components');
+const { formatDescription } = require("./common");
+const { config } = require("./config");
+const { getTypeData } = require("./components");
 
-const CONTENT_KEYWORD = '__CONTENT__';
+const CONTENT_KEYWORD = "__CONTENT__";
 
 const contentWrapersByTypeIdentifier = {
-  'enum': `{\r\n${CONTENT_KEYWORD} \r\n }`,
-  'interface': `{\r\n${CONTENT_KEYWORD}}`,
-  'type': `= ${CONTENT_KEYWORD}`,
-}
+  enum: `{\r\n${CONTENT_KEYWORD} \r\n }`,
+  interface: `{\r\n${CONTENT_KEYWORD}}`,
+  type: `= ${CONTENT_KEYWORD}`,
+};
 
-const getModelType = typeInfo => {
-  const { typeIdentifier, name: originalName, content, type, description } = getTypeData(typeInfo);
+const getModelType = (typeInfo) => {
+  let { typeIdentifier, name: originalName, content, type, description } = getTypeData(typeInfo);
+
+  if (config.generateUnionEnums && typeIdentifier === "enum") {
+    typeIdentifier = "type";
+  }
 
   if (!contentWrapersByTypeIdentifier[typeIdentifier]) {
-    throw new Error(`${typeIdentifier} - type identifier is unknown for this utility`)
+    throw new Error(`${typeIdentifier} - type identifier is unknown for this utility`);
   }
 
   const resultContent = formatters[type] ? formatters[type](content) : content;
@@ -27,11 +32,15 @@ const getModelType = typeInfo => {
     name,
     rawContent: resultContent,
     description: formatDescription(description),
-    content: _.replace(contentWrapersByTypeIdentifier[typeIdentifier], CONTENT_KEYWORD, resultContent)
-  }
-}
+    content: _.replace(
+      contentWrapersByTypeIdentifier[typeIdentifier],
+      CONTENT_KEYWORD,
+      resultContent,
+    ),
+  };
+};
 
 module.exports = {
   getModelType,
   checkAndRenameModelName,
-}
+};

src/modelTypes.js

@@ -0,0 +1,20 @@
+const { getFileContent } = require("./files");
+const { config } = require("./config");
+const { resolve } = require("path");
+
+const getTemplates = () => {
+  console.log(`✨ try to read templates from directory "${config.templates}"`);
+
+  return {
+    apiTemplate: getTemplate("api"),
+    clientTemplate: config.generateClient ? getTemplate("client") : null,
+    routeTypesTemplate: config.generateRouteTypes ? getTemplate("route-types") : null,
+  };
+};
+
+const getTemplate = (templateName) =>
+  getFileContent(resolve(config.templates, `./${templateName}.mustache`));
+
+module.exports = {
+  getTemplates,
+};

src/templates.js

@@ -1,8 +1,12 @@
 const _ = require("lodash");
+const { config } = require("./config");
 const { checkAndRenameModelName } = require("./modelNames");
 
 const formatters = {
-  enum: (content) => _.map(content, ({ key, value }) => `  ${key} = ${value}`).join(",\n"),
+  enum: (content) =>
+    _.map(content, ({ key, value }) =>
+      config.generateUnionEnums ? value : `  ${key} = ${value}`,
+    ).join(config.generateUnionEnums ? " | " : ",\n"),
   intEnum: (content) => _.map(content, ({ value }) => value).join(" | "),
   object: (content) =>
     _.map(content, (part) => {