[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

Author: js2me

CHANGELOG.md

@@ -1,11 +1,18 @@
 # next release  
 Breaking Changes:  
-  - Rename default typescript api file name (prev `api.ts`, now `Api.ts`)  
+  - 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  
-    ![api description](./assets/changelog_assets/right-comments-space.jpg)  
+    ![right comments space](./assets/changelog_assets/right-comments-space.jpg)  
 
 # 1.3.0  
 Features:  

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

@@ -17,18 +17,40 @@ program
   .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(
+    '-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 || '.')
 })

index.d.ts

@@ -3,16 +3,18 @@
   "version": "1.3.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.js

@@ -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),
   }
 }
 

package.json

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

src/apiConfig.js

@@ -1,5 +1,9 @@
 
 const config = {
+  /** CLI flag */
+  generateResponses: false,
+  /** CLI flag */
+  defaultResponseAsSuccess: false,
   /** CLI flag */
   generateRouteTypes: false,
   /** CLI flag */
@@ -14,4 +18,4 @@ const config = {
 module.exports = {
   addToConfig: configParts => Object.assign(config, configParts),
   config,
-} 
+}