Release 4.0.0 (#107)

* fix: handling x-omitempty property for definition properties (#68) * docs: update CHANGELOG * docs: update CHANGELOG * Migrate to eta (#88) * BREAKING CHANGE: migrate from mustache template engine to eta template engine * fix: merge conflicts after rebasing next Co-authored-by: Rafael Fakhreev <[email protected]> Co-authored-by: svolkov <[email protected]> * chore: update README (Contribution) * Refactor render layer (#90) * fix: handling x-omitempty property for definition properties (#68) * docs: update CHANGELOG * docs: update CHANGELOG; bump: up project version to 2.0.0 * BREAKING_CHANGE: renamed mustache templates, split client mustache template * BREAKING CHANGE: migrate from mustache template engine to eta template engine * feat: rewrite render layer - Respect single responsibility principle - Use Eta includeFile - Force use "No description" JSDoc comment * fix: handling x-omitempty property for definition properties (#68) * docs: update CHANGELOG * docs: update CHANGELOG * Migrate to eta (#88) * BREAKING CHANGE: migrate from mustache template engine to eta template engine * fix: merge conflicts after rebasing next Co-authored-by: Rafael Fakhreev <[email protected]> Co-authored-by: svolkov <[email protected]> * Sync code base * chore: delete unnecessary dir * Update index.js Fix default templates path Co-authored-by: svolkov <[email protected]> Co-authored-by: Rafael Fakhreev <[email protected]> * chore: revert back fix commit * BREAKING_CHANGE: return type of generateApi(); feat: modular option; chore: update HttpClient class (exportable) * fix: outOfModule modular * feat: complete data contracts imports for modular api modules, add prettier organize imports plugin * chore: remove console info * BREAKING_CHANGE: move generating route names into eta template * fix: problem of missing templates folder * fix: try to fix problem with not using prettier plugin * chore: refresh generated tests schemas * BREAKING_CHANGE: update all dependencies to latest * feat: improve types in index.d.ts file; refactor: processing templates folder, ETA templates, routes, schemas; feat: optional templates feature * chore: update CHANGELOG * feat: --extract-request-params option * fix: add missing generateApi params to .d.ts file; feat: add support x-enumNames field for enums * fix: enumNames getting from schema * feat: improve data-contracts.eta template, now data contracts formatting inside template * docs: update CHANGELOG * feat: hooks property for watching/modifying parsed parts of schema * fix: problem of complex types (`oneOf`, `allOf`) with `properties` field * chore: fix problem of wrong js docs comments for procedure call * feat: add pathArgs to routeInfo for routeName template * BREAKING_CHANGE: properties data and error in HttpResponse type have duck types * feat: add extraTemplate property for generateApi() * docs: update docs for --templates option * bump: up version to 4.0.0 * docs: update README * refactor: move all type identifiers\naming into constants like TS_KEYWORDS, SCHEMA_TYPES; chore: move prepareConfig to hooks.onPrepareConfig; feat: add onInit hook; feat: enumNamesAsValues * chore: try to fix travis yml * chore: remove description from modular api class * docs: update CHANGELOG Co-authored-by: Rafael Fakhreev <[email protected]> Co-authored-by: Rafael Fakhreev <[email protected]>
acacode · Jan 12, 2021 · 14b6d3d · 14b6d3d
1 parent 4a5d7ea
commit 14b6d3d
Show file tree

Hide file tree

Showing 120 changed files with 13,271 additions and 4,616 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 node_modules
 .vscode
+.idea
 swagger-test-cli.*
+swagger-test-cli
 dist
diff --git a/.travis.yml b/.travis.yml
@@ -6,16 +6,8 @@ cache:
   directories:
     - "node_modules"
 
-before_install:
-  - export PACKAGE_VERSION=$(node -p "require('./package.json').version")
-  - export PACKAGE_NAME=$(node -p "require('./package.json').name")
-  - export NPM_REMOTE_VERSION=$(npm view swagger-typescript-api version)
-  - export BRANCH_IS_TAG=$(node -p "/^([0-9].[0-9].[0-9]+((-(alpha|beta))|))$/.test('${TRAVIS_BRANCH}')")
-  - export GIT_LOG="$(git log --pretty=format:"* %s (%h)")"
-  - export PROJECT_NAME="acacode/swagger-typescript-api"
-
 install:
-  - npm ci
+  - npm i
 
 jobs:
   include:

diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -27,6 +27,14 @@
       "cwd": "${workspaceFolder}",
       "runtimeExecutable": "npm",
       "runtimeArgs": ["run-script", "cli:debug:yaml"]
+    },
+    {
+      "name": "Debug Node",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run-script", "node:debug"]
     }
   ]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,75 @@
 # next release  
 
+# 4.0.0  
+
+BREAKING_CHANGES:  
+- Migrate from [mustache](https://mustache.github.io/) template engine to [ETA](https://eta.js.org/) template engine. (Thanks @Fl0pZz)  
+- Critical change in `HttpResponse` type (Remove `D | null`, `E | null` unions)  
+```diff
+interface HttpResponse<D extends unknown, E extends unknown = unknown> extends Response {
+-  data: D | null;
++  data: D;
+-  error: E | null;
++  error: E;
+}
+```
+
+Features:  
+- `--modular` option. Allows to generate api class per module name.   
+  Example: [here](./tests/spec/modular)   
+- new templates on [ETA](https://eta.js.org/) (enhanced EJS) which can improve your templates! (Thanks @Fl0pZz)   
+  [ETA extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=shadowtime2000.eta-vscode) (thanks @shadowtime2000)  
+  Also moved out to templates:
+    - `procedure-call.eta` (request api method template)  
+    - `route-name.eta` (api method name template)  
+    - `route-docs.eta` (api method docs template)  
+
+  No worry about strange syntax it is very simple in usage :)  
+- Optional templates feature (Except templates using in `includeFile` `ETA` directive)  
+  Now you can store only the `ETA` templates which you need to change for yourself.  
+- `--extract-request-params` option. Generate path and query request params data contract and modify request payload args   
+  Example:  
+  ![extract-request-params](./assets/changelog_assets/extractRequestParams.jpg)  
+- Improve `data-contracts.eta` template. Added more power :)  
+- Add `extraTemplates` property for `generateApi()`. Allows to generate extra files via this tool.  
+- Add `hooks` property for `generateApi()`  
+  ```ts
+  hooks?: Partial<{
+    onCreateComponent: (component: SchemaComponent) => SchemaComponent | void;
+    onParseSchema: (originalSchema: any, parsedSchema: any) => any | void;
+    onCreateRoute: (routeData: ParsedRoute) => ParsedRoute | void;
+    /** Start point of work this tool (after fetching schema) */
+    onInit?: <C extends GenerateApiConfiguration["config"]>(configuration: C) => C | void;
+    /** Allows to customize configuration object before sending it to templates. */
+    onPrepareConfig?: <C extends GenerateApiConfiguration>(currentConfiguration: C) => C | void;
+  }>;
+  ```
+  ```ts
+    generateApi({
+      input: "./schema.json",
+      output: "./__generated__",
+      hooks: {
+        onCreateComponent(component) {
+          // do something
+          return component;
+        },
+        // ...
+      }
+    })
+  ```
+
+Internal:  
+- Update all dependencies to latest  
+
+Fixes:  
+- `x-enumNames` support for enums  
+- Problem of complex types (`oneOf`, `allOf`) with `properties` field  
+- `additionalProperties: true` should make `[key: string]: any` for object types (Thanks @brookjordan for issue #103)  
+
+Common:  
+- `HttpClient` is exportable by default  
+- Improve typings when use `swagger-typescript-api` with NodeJS (`index.d.ts`)  
+
 # 3.1.2  
 Fixes:  
 - axios vulnerability (#101 issue, thanks @Mvbraathen)  

diff --git a/README.md b/README.md
@@ -2,6 +2,7 @@
 
 [![Greenkeeper badge](https://badges.greenkeeper.io/acacode/swagger-typescript-api.svg)](https://greenkeeper.io/)
 [![NPM badge](https://img.shields.io/npm/v/swagger-typescript-api.svg)](https://www.npmjs.com/package/swagger-typescript-api)
+[![Build Status](https://travis-ci.org/acacode/swagger-typescript-api.svg?branch=master)](https://travis-ci.org/acacode/swagger-typescript-api)
 
 <img src="https://raw.githubusercontent.com/acacode/swagger-typescript-api/master/assets/swagger-typescript-api-logo.png" align="left"
      title="swagger-typescript-api logo by js2me" width="93" height="180">
@@ -23,9 +24,8 @@ Any questions you can ask [**here**](https://github.com/acacode/swagger-typescri
 
 All examples you can find [**here**](https://github.com/acacode/swagger-typescript-api/tree/master/tests)  
 
-## 🛑 It is the latest version on mustache templates   
-Next versions 4.0.0+ will use the [ETA](https://eta.js.org/docs/syntax) templates.  
-If you want to create fork with `mustache` templates use `mustache-latest` branch  
+## 🛑 It is new version with [ETA](https://eta.js.org/docs/syntax) templates  
+Version with `mustache` templates is `>4.0.0`  
 
 ## 📄 Usage  
 
@@ -47,9 +47,13 @@ Options:
   --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
+  --enum-names-as-values        use values in 'x-enumNames' as enum values (not only as keys) (default: false)
   --js                          generate js api module with declaration file (default: false)
+  --extract-request-params      extract request params to data contract (default: false)
+                                Also combine path params and query params into one object
   --module-name-index <number>  determines which path index should be used for routes separation (default: 0)
                                 (example: GET:/fruites/getFruit -> index:0 -> moduleName -> fruites)
+  --modular                     generate separated files for http client, data contracts, and routes (default: false)
   -h, --help                    display help for command
 ```
 
@@ -67,15 +71,23 @@ generateApi({
   name: "MySuperbApi.ts", // name of output typescript file
   url: 'http://api.com/swagger.json', // url where located swagger schema
 })
-  .then(sourceFile => fs.writeFile(path, sourceFile))
+  .then(({ files, configuration }) => {
+    files.forEach(({ content, name }) => {
+      fs.writeFile(path, content);
+    });
+  })
   .catch(e => console.error(e))
 
 // example with local file  
 generateApi({
   name: "ApiModule.ts", // name of output typescript file
   input: resolve(process.cwd(), './foo/swagger.json') // path to swagger schema
 })
-  .then(sourceFile => fs.writeFile(path, sourceFile))
+  .then(({ files, configuration }) => {
+    files.forEach(({ content, name }) => {
+      fs.writeFile(path, content);
+    });
+  })
   .catch(e => console.error(e))
 
 // example with parsed schema  
@@ -98,19 +110,36 @@ generateApi({
     // ...
   }
 })
-  .then(sourceFile => fs.writeFile(path, sourceFile))
+  .then(({ files, configuration }) => {
+    files.forEach(({ content, name }) => {
+      fs.writeFile(path, content);
+    });
+  })
   .catch(e => console.error(e))
 
 ```
 
 
 ## 💎 options   
 ### **`--templates`**  
-This option should be used in cases when you don't want to use default `swagger-typescript-api` output structure  
+This option needed for cases when you don't want to use default `swagger-typescript-api` output structure  
+
+Templates:  
+- `api.eta` - Api class module  
+- `data-contracts.eta` - all types (data contracts) from swagger schema  
+- `http-client.eta` - HttpClient class module  
+- `procedure-call.eta` - route in Api class  
+- `route-docs.eta` - documentation for route in Api class  
+- `route-name.eta` - route name for route in Api class  
+- `route-type.eta` - *(`--route-types` option)*  
+- `route-types.eta` - *(`--route-types` option)*  
+
 How to use it:  
-1. copy [**swagger-typescript-api templates**](https://github.com/acacode/swagger-typescript-api/tree/mustache-latest/src/templates/defaults) into your place in project  
+1. copy swagger-typescript-api templates into your place in project
+    - from [/templates/default](https://github.com/acacode/swagger-typescript-api/tree/next/templates/default) for single api file  
+    - from [/templates/modular](https://github.com/acacode/swagger-typescript-api/tree/next/templates/modular) for multiple api files (with `--modular` option)  
 1. add `--templates PATH_TO_YOUR_TEMPLATES` option  
-2. modify [Mustache](https://mustache.github.io/) templates as you like  
+2. modify [ETA](https://eta.js.org/docs/syntax) templates as you like  
 
 ### **`--module-name-index`**  
 This option should be used in cases when you have api with one global prefix like `/api`   
@@ -139,10 +168,10 @@ When we change it to `--module-name-index 1` then Api class have two properties
 
 ## 🛠️ Contribution  
 
-You can manually check your changes at schemas in `tests` folder before create a PR.  
-To do that have scripts:  
-    - `npm run generate` - generate API modules from schemas in `tests` folder  
-    - `npm run validate` - validate generated API modules via TypeScript  
+
+❗❗❗ Please use the `next` branch :)   
+
+If you need to check your changes at schemas in `tests` folder before create a PR just run command `npm run test:all`  
 
 ## 📝 License  
 Licensed under the [MIT License](https://github.com/acacode/swagger-typescript-api/blob/master/LICENSE).
diff --git a/assets/changelog_assets/extractRequestParams.jpg b/assets/changelog_assets/extractRequestParams.jpg