@team-supercharge/oasg 8.0.2 → 9.1.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [9.1.0](https://gitlab.com/team-supercharge/oasg/compare/v9.0.0...v9.1.0) (2023-02-28)
+
+
+### Features
+
+* **openapi:** add cleanup steps for openapi target ([01626ca](https://gitlab.com/team-supercharge/oasg/commit/01626ca1454be73afb420310503fd6af3b0164f9))
+
+## [9.0.0](https://gitlab.com/team-supercharge/oasg/compare/v8.0.2...v9.0.0) (2023-02-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* **spring-kotlin, spring, feign:** skip inline schema reusing by default
+
+### Features
+
+* **spring-kotlin, spring, feign:** skip inline schema reusing by default ([c125332](https://gitlab.com/team-supercharge/oasg/commit/c125332cbd59dbd31b2e257060a716950ed3f03a))
+
 ### [8.0.2](https://gitlab.com/team-supercharge/oasg/compare/v8.0.1...v8.0.2) (2023-02-24)
 
 

package/README.md

@@ -651,6 +651,7 @@ describe('Auth', function () {
 | bundle | Bundle specification into a single file | N | `true` |
 | sortSchemas | Sort `components.schemas` alphabetically | N | `true` |
 | decorators | Array of files for decorator functions | N | `[]` |
+| cleanup | Cleans specification from unused paths, tags and schemas | N | `true` |
 
 The target specification is by default bundled into a single file (resolving external dependencies) using the [@redocly/cli package's](https://www.npmjs.com/package/@redocly/cli) `bundle` command.
 
@@ -668,7 +669,8 @@ Full example with decorators:
   "fileName": "my-openapi-file.yaml",
   "bundle": false,
   "sortSchemas": false,
-  "decorators": ["decorators/one", "decorators/two"]
+  "decorators": ["decorators/one", "decorators/two"],
+  "cleanup": false
 }
 ```
 
@@ -684,6 +686,11 @@ function decorate(document) {
 exports.decorate = decorate;
 ```
 
+After the decorators have run, the specification is by default cleaned up (can be turned off by setting the `"cleanup": false` option):
+  - `paths` with no methods in them are removed
+  - `tags` with no endpoints using them are removed
+  - `components` that are unused are removed (only if `bundle` option is also enabled)
+
 ## Template Customization
 
 Using the comming `templateDir` config parameter there is a possibility to customize the templates used during generation.
@@ -705,6 +712,66 @@ The **"project level"** customization can be configured using the `templateDir`
 
 This section covers the breaking changes and their migrations across major version upgrades.
 
+### From `8.x.x` to `9.0.0`
+
+#### Skip Reusing Schemas in `spring-kotlin`, `spring` and `feign`
+
+The newer versions of OpenAPI Generator adds the flag to skip the [automatic inline schema reusing](https://openapi-generator.tech/docs/customization/#inline-schema-naming) logic (see example what this means below).
+
+From _OASg_ 9.0.0 the **default and recommended behaviour is to skip schema reusing** for the targets above. If you wish to resume schema reusing for compatibility reasons, add `--inline-schema-name-defaults SKIP_SCHEMA_REUSE=false` to `generatorCustomArgs` in the project's `config.json`
+
+Take the following schema:
+
+  ```yaml
+  schemas:
+    Message:
+      type: object
+      properties:                 # messages have a topic and text
+        topic:
+          type: object
+          properties:             # topics have id and name
+            id:
+              type: string
+            name:
+              type: string
+        text:
+          type: string
+
+    User:
+      type: object
+      properties:                 # users have a company, and firstName and lastName
+        company:
+          type: object
+          properties:             # copmanies have id and name
+            id:
+              type: string
+            name:
+              type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+  ```
+
+Previously the following DTO objects were generated from this schema:
+
+```java
+Message(MessageTopic topic, String text)
+MessageTopic(String id, String name)
+User(MessageTopic company, String firstName, String lastName)
+```
+
+Previously the generator reused internal schemas which had the exact same fields, ending up with a `MessageTopic` object for the users' Company, just because both had `id` and `name` string properties.
+
+With defining `SKIP_SCHEMA_REUSE=true` the output will be more verbose, but schema names won't get mixed up:
+
+```java
+Message(MessageTopic topic, String text)
+MessageTopic(String id, String name)
+User(UserCompany company, String firstName, String lastName)
+UserCompany(String id, String name)
+```
+
 ### From `7.x.x` to `8.0.0`
 
 #### Linting

package/bin/openapi-target.js

@@ -4,6 +4,10 @@ const SwaggerParser = require("@apidevtools/swagger-parser");
 const { dump } = require(`${__dirname}/dump.js`);
 const { exec } = require(`${__dirname}/exec.js`);
 
+function bundleSpec(source, target, remove) {
+  exec(`npx redocly bundle ${source} --keep-url-references${remove ?  ' --remove-unused-components' : ''} --output ${target}`, 'pipe');
+}
+
 async function openApiTarget(target, source, version) {
   const outDir = `out/${target.id}`;
   let outFile = target.fileName || `openapi.yaml`;
@@ -17,7 +21,7 @@ async function openApiTarget(target, source, version) {
   // bundle spec to a single file by default
   const bundle = target.bundle === undefined || target.bundle;
   if (bundle) {
-    exec(`npx redocly bundle ${source} --keep-url-references --output ${outFile}`, 'pipe');
+    bundleSpec(source, outFile, false);
     console.log(`bundled specification`);
   }
 
@@ -58,8 +62,68 @@ async function openApiTarget(target, source, version) {
     console.log(`applied decorator '${decoratorFile}'`);
   });
 
+  // clean up unused things
+  const cleanup = target.cleanup === undefined || target.cleanup;
+  if (cleanup) {
+    const removedPaths = [];
+    const removedTags = [];
+    const usedTags = [];
+
+    // remove empty paths & gather tags
+    const paths = document.paths;
+    for (const pathKey in paths) {
+      const path = document.paths[pathKey];
+
+      if (Object.keys(path).length === 0) {
+        removedPaths.push(pathKey);
+        delete paths[pathKey];
+      }
+
+      for (const methodKey in path) {
+        const operation = path[methodKey];
+
+        operation.tags.forEach(tag => {
+          if (!usedTags.includes(tag)) {
+            usedTags.push(tag);
+          }
+        });
+      }
+    }
+
+    if (removedPaths.length !== 0) {
+      console.log(`cleaned up unused paths:\n  ${removedPaths.join('\n  ')}`);
+    }
+
+    // remouve unused tags
+    const tags = [...document.tags];
+    tags.forEach(tag => {
+      if (!usedTags.includes(tag.name)) {
+        removedTags.push(tag.name);
+        document.tags.splice(document.tags.indexOf(tag), 1);
+      }
+    });
+
+    if (removedTags.length !== 0) {
+      console.log(`cleaned up unused tags:\n  ${removedTags.join('\n  ')}`);
+    }
+  }
+
   // write file
   dump(document, outFile);
+
+  // re-bundle to remove unused components
+  if (cleanup && bundle) {
+    console.log(`re-bundling specification to remove unused components`);
+    let currentSize;
+    let bundledSize;
+    do {
+      currentSize = fs.statSync(outFile).size;
+      bundleSpec(outFile, outFile, true);
+      console.log('.');
+      bundledSize = fs.statSync(outFile).size;
+    }
+    while (bundledSize !== currentSize)
+  }
 }
 
 exports.openApiTarget = openApiTarget;

package/config.schema.yml

@@ -302,6 +302,8 @@ targets:
             type: array
             items:
               type: string
+          cleanup:
+            type: boolean
 
 definitions:
   # default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-supercharge/oasg",
-  "version": "8.0.2",
+  "version": "9.1.0",
   "description": "Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them",
   "author": "Supercharge",
   "license": "MIT",

package/targets/feign/generator-config.json

@@ -19,6 +19,7 @@
   },
   "inlineSchemaNameDefaults": {
     "arrayItemSuffix": "",
-    "mapItemSuffix": ""
+    "mapItemSuffix": "",
+    "SKIP_SCHEMA_REUSE": "true"
   }
 }

package/targets/spring/generator-config.json

@@ -20,6 +20,7 @@
   },
   "inlineSchemaNameDefaults": {
     "arrayItemSuffix": "",
-    "mapItemSuffix": ""
+    "mapItemSuffix": "",
+    "SKIP_SCHEMA_REUSE": "true"
   }
 }

package/targets/spring-kotlin/generator-config.json

@@ -20,6 +20,7 @@
   },
   "inlineSchemaNameDefaults": {
     "arrayItemSuffix": "",
-    "mapItemSuffix": ""
+    "mapItemSuffix": "",
+    "SKIP_SCHEMA_REUSE": "true"
   }
 }