release 1.4.0 (#20)

* test(internal): speed improve validate generated ts api modules

* BREAKING_CHANGE: default typescript api file name (api.ts -> Api.ts)

* feat: improve response body type definitions

* chore(docs): add gtihub funding

* [Bugfix] Response type does not de-reference $refs (#19)

* chore: add common test schemas

* refactor: encapsulate nodejs.fs module usage; feat: dereference components responses + improve types

* chore: add specific comments for calling src/index.js on unix like machines via nodejs

* chore: update gitignore (add hidden test cli file)

* fix: JSDOC comments

* [Features] - response declarations, "default" status codes as success response types (#17)

* feat: add @returns keywords into each request comments description (request responses)

* feat: prettify descriptions

* feat: add response declarations in request description; feat: typed bad responses

* feat: -d, --default-as-success option (ability to use "default" success response status code)

* chore: add common test schemas

* fix: description of defaultResponseAsSuccess option

* chore: rename setConfig to addToConfig

* chore: add specific comments for calling src/index.js on unix like machines via nodejs

* feat: move responses declarations into flag '-r, --responses'; chore(test): add manual test for new option; docs: update CHANGELOG + README

* fix: format description (end \n character)

* bump: up version to 1.4.0

Author: js2me

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+open_collective: acacode
+ko_fi: acacode

.gitignore

@@ -1,3 +1,3 @@
 node_modules
 .vscode
-swagger-test-cli.ts
+swagger-test-cli.*

.vscode/launch.json

@@ -5,13 +5,22 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Launch via npm",
+      "name": "Debug generate",
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}",
       "runtimeExecutable": "npm",
       "runtimeArgs": ["run-script", "generate:debug"],
       "port": 9229
+    },
+    {
+      "name": "Debug CLI",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run-script", "cli:debug"],
+      "port": 9229
     }
   ]
 }

CHANGELOG.md

@@ -1,3 +1,19 @@
+# 1.4.0  
+Breaking Changes:  
+  - Rename default typescript output api file name (prev `api.ts`, now `Api.ts`)  
+Features:  
+  - `-d, --default-as-success` option. Allows to use "default" status codes as success response type  
+  - `-r, --responses` option. Response declarations in request rescription  
+    This option adds comments of the possible responses from request  
+    ![responses comments](./assets/changelog_assets/responses-comments.jpg)  
+    Also typings for `.catch()` callback  
+    ![responses catch types](./assets/changelog_assets/responses-catch-types.jpg)  
+  - Improve response body type definitions  
+  - Types for bad responses  
+Changes:  
+  - \[minor\] fix jsdoc comments space  
+    ![right comments space](./assets/changelog_assets/right-comments-space.jpg)  
+
 # 1.3.0  
 Features:  
   - Api module description from schema info  

README.md

@@ -25,18 +25,23 @@ All examples you can find [**here**](https://github.com/acacode/swagger-typescri
 
 ## 📄 Usage  
 
-```cool
+```muse
 Usage: sta [options]
 Usage: swagger-typescript-api [options]
 
 Options:
-  -v, --version          output the current version
-  -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")
-  --route-types          generate type definitions for API routes (default: false)
-  --no-client            do not generate an API class
-  -h, --help             output usage information
+  -v, --version             output the current version
+  -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")
+  -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  
+  --route-types             generate type definitions for API routes (default: false)
+  --no-client               do not generate an API class
+  -h, --help                output usage information
 ```
 
 Also you can use `npx`:  

assets/changelog_assets/responses-catch-types.jpg

@@ -1,5 +1,15 @@
 
-interface BaseGenerateApiParams {
+interface GenerateApiParams {
+
+  /**
+   * path to swagger schema
+   */
+  input: string;
+
+  /**
+   * url to swagger schema
+   */
+  url: string;
 
   /**
    * default 'api.ts'
@@ -10,23 +20,29 @@ interface BaseGenerateApiParams {
    * path to folder where will been located the created api module
    */
   output?: string;
-}
-
-interface LocalFileGenerateApiParams extends BaseGenerateApiParams {
+  
+  /**
+   * generate type definitions for API routes (default: false)
+   */
+  generateRouteTypes?: boolean;
 
   /**
-   * path to swagger schema
+   * do not generate an API class
    */
-  input: string;
-}
+  generateClient?: boolean;
 
-interface UrlGenerateApiParams extends BaseGenerateApiParams {
+  /**
+   * 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;
 
   /**
-   * url to swagger schema
+   * generate additional information about request responses
+   * also add typings for bad responses
    */
-  url: string;
+  generateResponses?: boolean;
 }
 
-export declare function generateApi(params: LocalFileGenerateApiParams): Promise<string>
-export declare function generateApi(params: UrlGenerateApiParams): Promise<string>
+export declare function generateApi(params: Omit<GenerateApiParams, "url">): Promise<string>
+export declare function generateApi(params: Omit<GenerateApiParams, "input">): Promise<string>

assets/changelog_assets/responses-comments.jpg

@@ -16,19 +16,41 @@ program
   .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')
+  .option('-n, --name <name>', 'name of output typescript api file', 'Api.ts')
+  .option(
+    '-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
+  )
+  .option(
+    '-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);
 
 program.parse(process.argv);
 
-const { path, output, name, routeTypes, client } = program;
+const {
+  path,
+  output,
+  name,
+  routeTypes,
+  client,
+  defaultAsSuccess,
+  responses,
+} = program;
 
 generateApi({
   name,
   url: path,
   generateRouteTypes: routeTypes,
   generateClient: client,
+  defaultResponseAsSuccess: defaultAsSuccess,
+  generateResponses: responses,
   input: resolve(process.cwd(), path),
   output: resolve(process.cwd(), output || '.')
 })

assets/changelog_assets/right-comments-space.jpg

@@ -1,17 +1,20 @@
 {
   "name": "swagger-typescript-api",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Create typescript api module from swagger schema",
   "scripts": {
-    "cli": "node index.js -p ./tests/schemas/v3.0/personal-api-example.json -n swagger-test-cli.ts",
+    "cli": "node index.js -d -p ./swagger-test-cli.json -n swagger-test-cli.ts",
+    "cli:debug": "node  --nolazy --inspect-brk=9229 index.js -p ./tests/schemas/v2.0/adafruit.yaml -n swagger-test-cli.ts",
     "cli:help": "node index.js -h",
-    "test:all": "npm-run-all generate validate test:routeTypes test:noClient --continue-on-error",
+    "test:all": "npm-run-all generate validate test:routeTypes test:noClient test:defaultAsSuccess test:responses --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:noClient": "node tests/spec/noClient/test.js",
+    "test:defaultAsSuccess": "node tests/spec/defaultAsSuccess/test.js",
+    "test:responses": "node tests/spec/responses/test.js"
   },
   "author": "acacode",
   "license": "MIT",

index.d.ts

@@ -1,4 +1,4 @@
-const _ = require("lodash")
+const { formatDescription } = require("./common");
 
 const createApiConfig = ({ info, servers, }) => {
   const server = (servers && servers[0]) || { url: '' }
@@ -29,7 +29,7 @@ const createApiConfig = ({ info, servers, }) => {
     baseUrl: server.url,
     title: info.title,
     version: info.version,
-    description: _.replace(info.description, /\*\//g, "*\/"),
+    description: formatDescription(info.description),
   }
 }
 

index.js

@@ -0,0 +1,25 @@
+const _ = require("lodash");
+
+module.exports = {
+  formatDescription: (description, inline) => {
+    let prettified = description;
+
+    prettified = _.replace(prettified, /\*\//g, "*\/");
+
+    const hasMultipleLines = _.includes(prettified, '\n');
+
+    if (!hasMultipleLines)
+      return prettified;
+
+    if (inline) {
+      return _(prettified)
+        .split(/\n/g)
+        .map(part => _.trim(part))
+        .compact()
+        .join(' ')
+        .valueOf()
+    }
+
+    return _.replace(prettified, /\n$/g, '')
+  }
+}

package-lock.json

@@ -0,0 +1,60 @@
+const _ = require("lodash");
+const { parseSchema } = require("./schema");
+const { addToConfig } = require("./config");
+
+/**
+ * 
+ * @typedef TypeInfo
+ * {
+ *    typeName: "Foo",
+ *    componentName: "schemas",
+ *    rawTypeData: {...},
+ *    typeData: {...} (result parseSchema())
+ * } 
+ */
+
+/**
+ * @returns {{ "#/components/schemas/Foo": TypeInfo, ... }}
+ */
+const createComponentsMap = components => {
+  const componentsMap = _.reduce(components, (map, component, componentName) => {
+    _.each(component, (rawTypeData, typeName) => {
+      // only map data for now
+      map[`#/components/${componentName}/${typeName}`] = {
+        typeName,
+        rawTypeData,
+        componentName,
+        typeData: null,
+      }
+    })
+    return map;
+  }, {})
+
+  addToConfig({ componentsMap })
+
+  return componentsMap;
+}
+
+
+
+/**
+ * @returns {TypeInfo[]}
+ */
+const filterComponentsMap = (componentsMap, componentName) =>
+  _.filter(componentsMap, (v, ref) => _.startsWith(ref, `#/components/${componentName}`))
+
+
+/** @returns {{ type, typeIdentifier, name, description, content }} */
+const getTypeData = typeInfo => {
+  if (!typeInfo.typeData) {
+    typeInfo.typeData = parseSchema(typeInfo.rawTypeData, typeInfo.typeName)
+  }
+
+  return typeInfo.typeData;
+}
+
+module.exports = {
+  getTypeData,
+  createComponentsMap,
+  filterComponentsMap,
+}

package.json

@@ -0,0 +1,21 @@
+
+const config = {
+  /** CLI flag */
+  generateResponses: false,
+  /** CLI flag */
+  defaultResponseAsSuccess: false,
+  /** CLI flag */
+  generateRouteTypes: false,
+  /** CLI flag */
+  generateClient: true,
+  /** parsed swagger schema from getSwaggerObject() */ 
+  swaggerSchema: null,
+  /** { "#/components/schemas/Foo": @TypeInfo, ... } */
+  componentsMap: {},
+}
+
+/** needs to use data everywhere in project */
+module.exports = {
+  addToConfig: configParts => Object.assign(config, configParts),
+  config,
+} 

src/apiConfig.js

@@ -0,0 +1,6 @@
+module.exports = {
+  DEFAULT_PRIMITIVE_TYPE: "any",
+  DEFAULT_BODY_ARG_NAME: "data",
+  DEFAULT_CONTENT_TYPE: "application/json",
+  SUCCESS_RESPONSE_STATUS_RANGE: [200, 300],
+}

src/common.js

@@ -0,0 +1,22 @@
+const _ = require("lodash");
+const fs = require("fs");
+const { resolve } = require("path");
+
+const getFileContent = path =>
+  fs.readFileSync(path, { encoding: 'UTF-8' })
+
+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`))
+
+module.exports = {
+  getTemplate,
+  createFile,
+  pathIsExist,
+  getFileContent,
+}