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 || '.')
 })