@team-supercharge/oasg 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
 
+## [7.1.0](https://gitlab.com/team-supercharge/oasg/compare/v7.0.0...v7.1.0) (2023-02-22)
+
+
+### Features
+
+* merge complete specifications with every possible field ([60b2e61](https://gitlab.com/team-supercharge/oasg/commit/60b2e614fd72238a9b64a77cc975de24f08f75cb))
+* **openapi:** add openapi target for outputting documentation ([051da63](https://gitlab.com/team-supercharge/oasg/commit/051da63eee8bf3eede9c5ca84ea130713128596c))
+* **openapi:** add option to sort schemas alphabetically ([0611f5e](https://gitlab.com/team-supercharge/oasg/commit/0611f5e2ba6d65bdb78fd8666a98f69c4d3edd8a))
+* **openapi:** bundle specifications using @redocly/cli ([d50fd9c](https://gitlab.com/team-supercharge/oasg/commit/d50fd9c5a987c8dfe476b8659710dcbf52557dca))
+* use js-yaml to dump YAML in a more nicely formatted way ([8728bcd](https://gitlab.com/team-supercharge/oasg/commit/8728bcd8c3442531290d487571ae1652ebe5b691))
+
+
+### Refactoring
+
+* handle dumping YAML files centralized ([1d16b05](https://gitlab.com/team-supercharge/oasg/commit/1d16b059d180bb655befe2e0d905017bd94309b4))
+
 ## [7.0.0](https://gitlab.com/team-supercharge/oasg/compare/v6.2.1...v7.0.0) (2023-02-21)
 
 

package/README.md

@@ -31,6 +31,7 @@ Design APIs in OpenAPI 3.0 format, lint them, and generate client/server package
     * [Python](#python)
     * [Contract-Testing](#contract-testing)
     * [NestJS](#nestjs)
+    * [OpenAPI](#openapi)
 * [Template Customization](#template-customization)
 * [Migration Guide](#migration-guide)
 * [Roadmap](#roadmap)
@@ -559,6 +560,55 @@ describe('Auth', function () {
 - array of enums in query/header/path/form parameters are not validated (stay as string)
 - no multidimensional array validation in DTOs
 
+#### OpenAPI
+
+```json
+{
+  "id": "api-docs",
+  "type": "openapi",
+  "source": "source-simple",
+}
+```
+
+|Parameter| Description| Required | Default |
+|-|-|-|-|
+| fileName | Name of the generated file | N | `openapi.yaml` |
+| bundle | Bundle specification into a single file | N | `true` |
+| sortSchemas | Sort `components.schemas` alphabetically | N | `true` |
+| decorators | Array of files for decorator functions | N | `[]` |
+
+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.
+
+> ⚠️ It is higly recommended to keep `bundle` on, as external refs won't be part of the target artifact.
+
+Decorator files must export a `decorate(document)` function which transforms the parsed OpenAPI document and returns it at the end of the function.
+
+Full example with decorators:
+
+```json
+{
+  "id": "api-docs",
+  "type": "openapi",
+  "source": "source-simple",
+  "fileName": "my-openapi-file.yaml",
+  "bundle": false,
+  "sortSchemas": false,
+  "decorators": ["decorators/one", "decorators/two"]
+}
+```
+
+```js
+// decorators/one.js
+
+function decorate(document) {
+  document.info.title = 'My Custom Decorated Title';
+
+  return document;
+}
+
+exports.decorate = decorate;
+```
+
 ## Template Customization
 
 Using the comming `templateDir` config parameter there is a possibility to customize the templates used during generation.

package/bin/bundler.js

@@ -0,0 +1,34 @@
+const crypto = require('crypto');
+const fs = require('fs');
+
+const { exec } = require(`${__dirname}/exec.js`);
+
+async function bundleSpecification(source, file) {
+  // do NOT bundle by default for any sources
+  if (source.bundle === undefined || source.bundle === false) {
+    return file;
+  }
+
+  let outFile;
+
+  if (!file.startsWith("./out/.tmp")) {
+    if (!fs.existsSync('./out')) {
+      fs.mkdirSync('./out');
+    }
+
+    if (!fs.existsSync('./out/.tmp')) {
+      fs.mkdirSync('./out/.tmp');
+    }
+
+    outFile = `./out/.tmp/${source.id}-${crypto.randomBytes(4).readUInt32LE(0)}`;
+  } else {
+    outFile = file;
+  }
+
+  // using @redocly/cli to bundle
+  exec(`npx redocly bundle ${file} --keep-url-references --output ${outFile}`);
+
+  return outFile;
+}
+
+exports.bundleSpecification = bundleSpecification;

package/bin/dump.js

@@ -0,0 +1,11 @@
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+async function dump(document, fileName) {
+  const content = yaml.dump(document, { lineWidth: -1 });
+  fs.writeFileSync(fileName, content);
+
+  return fileName;
+}
+
+exports.dump = dump;

package/bin/exec.js

@@ -0,0 +1,14 @@
+const { exit } = require('process');
+const { execSync } = require('child_process');
+
+function exec(command, stdio) {
+  try {
+    execSync(command, { stdio: stdio || 'inherit' });
+  }
+  catch (e) {
+    console.error(e.message);
+    exit(1);
+  }
+}
+
+exports.exec = exec;

package/bin/merger.js

@@ -1,65 +1,64 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const YAML = require('yamljs');
 const SwaggerParser = require("@apidevtools/swagger-parser");
 
+const { dump } = require(`${__dirname}/dump.js`);
+
 async function merge(source) {
-	if (!fs.existsSync('./out')) {
-		fs.mkdirSync('./out');
-	}
+  if (!fs.existsSync('./out')) {
+    fs.mkdirSync('./out');
+  }
 
-	if (source.inputs.length == 1) {
-		return source.inputs[0];
-	}
+  if (source.inputs.length == 1) {
+    return source.inputs[0];
+  }
 
-	if (!fs.existsSync('./out/.tmp')) {
-		fs.mkdirSync('./out/.tmp');
-	}
-	const outFile = `./out/.tmp/${source.id}-${crypto.randomBytes(4).readUInt32LE(0)}.yaml`;
+  if (!fs.existsSync('./out/.tmp')) {
+    fs.mkdirSync('./out/.tmp');
+  }
+  const outFile = `./out/.tmp/${source.id}-${crypto.randomBytes(4).readUInt32LE(0)}.yaml`;
 
-	const content = await mergeDocuments(source.inputs);
+  const document = await mergeDocuments(source.inputs);
 
-	fs.writeFileSync(outFile, content);
+  dump(document, outFile);
 
-	return outFile;
+  return outFile;
 }
 
 async function mergeDocuments(documents) {
-	let finalDoc = await SwaggerParser.parse(documents[0]);
-	finalDoc = resolveExternalSpecifications(documents[0], finalDoc);
-
-	for (var i = 1; i < documents.length; i++) {
-		let nextDoc = await SwaggerParser.parse(documents[i]);
-		nextDoc = resolveExternalSpecifications(documents[i], nextDoc);
-		finalDoc = mergeDocument(finalDoc, nextDoc);
-	}
+  let finalDoc = await SwaggerParser.parse(documents[0]);
+  finalDoc = resolveExternalSpecifications(documents[0], finalDoc);
 
-	const data = YAML.dump(finalDoc);
+  for (var i = 1; i < documents.length; i++) {
+    let nextDoc = await SwaggerParser.parse(documents[i]);
+    nextDoc = resolveExternalSpecifications(documents[i], nextDoc);
+    finalDoc = mergeDocument(finalDoc, nextDoc);
+  }
 
-	return data;
+  return finalDoc;
 }
 
 function resolveExternalSpecifications(currentFile, document) {
-	const files = new Set([]);
+  const files = new Set([]);
 
-	getAllReferencedFiles(document, files);
+  getAllReferencedFiles(document, files);
 
-	if (files.size > 0) {
-		files.forEach(refFile => {
-			const newRefFile = getAbsolutePathForReferencedFile(currentFile, refFile);
+  if (files.size > 0) {
+    files.forEach(refFile => {
+      const newRefFile = getAbsolutePathForReferencedFile(currentFile, refFile);
 
-			document = updateReferences(document, refFile, newRefFile);
-		})
-	} else {
-		console.log('No external files');
-	}
+      document = updateReferences(document, refFile, newRefFile);
+    })
+  } else {
+    console.log('No external files');
+  }
 
-	return document;
+  return document;
 }
 
 function getAllReferencedFiles(document, files) {
-	if (typeof document === 'object') {
+  if (typeof document === 'object') {
     // iterating over the object using for..in
     for (var keys in document) {
       //checking if the current value is an object itself
@@ -80,53 +79,53 @@ function getAllReferencedFiles(document, files) {
       } else {
         // else checking for ref property, getting the file path if its an external local path
         if (keys === "$ref") {
-					if (document[keys].startsWith(".")) {
-						const externalFilePath = document[keys].split('#')[0];
-						files.add(externalFilePath);
-					}
+          if (document[keys].startsWith(".")) {
+            const externalFilePath = document[keys].split('#')[0];
+            files.add(externalFilePath);
+          }
         }
       }
     }
-	}
-	return document;
+  }
+  return document;
 }
 
 function getAbsolutePathForReferencedFile(currentFile, referencedFile) {
-	const originalPath = process.cwd();
+  const originalPath = process.cwd();
 
-	process.chdir(path.dirname(`${originalPath}/${currentFile}`));
+  process.chdir(path.dirname(`${originalPath}/${currentFile}`));
 
-	const absolutePath = path.resolve(process.cwd(), referencedFile);
+  const absolutePath = path.resolve(process.cwd(), referencedFile);
 
-	// move back
-	process.chdir(originalPath);
+  // move back
+  process.chdir(originalPath);
 
-	return absolutePath;
+  return absolutePath;
 }
 
 function moveReferencedFiles(folderName, currentFile, files) {
-	// save current process dir
-	const originalPath = process.cwd();
+  // save current process dir
+  const originalPath = process.cwd();
 
-	// create output temp directory
-	const outputFolderPath = `${originalPath}/out/.tmp/${folderName}`;
-	fs.mkdirSync(outputFolderPath);
+  // create output temp directory
+  const outputFolderPath = `${originalPath}/out/.tmp/${folderName}`;
+  fs.mkdirSync(outputFolderPath);
 
-	// move to original file directory, in order to find referenced files for copy command
-	process.chdir(path.dirname(`${originalPath}/${currentFile}`));
+  // move to original file directory, in order to find referenced files for copy command
+  process.chdir(path.dirname(`${originalPath}/${currentFile}`));
 
-	files.forEach(item => {
-		const outName = path.basename(item);
-		// copy referenced file to tmp output folder
-		fs.copyFileSync(item, `${outputFolderPath}/${outName}`);
-	});
+  files.forEach(item => {
+    const outName = path.basename(item);
+    // copy referenced file to tmp output folder
+    fs.copyFileSync(item, `${outputFolderPath}/${outName}`);
+  });
 
-	// move back
-	process.chdir(originalPath);
+  // move back
+  process.chdir(originalPath);
 }
 
 function updateReferences(document, oldValue, newValue) {
-	if (typeof document === 'object') {
+  if (typeof document === 'object') {
     // iterating over the object using for..in
     for (var keys in document) {
       //checking if the current value is an object itself
@@ -146,36 +145,50 @@ function updateReferences(document, oldValue, newValue) {
       } else {
         // else checking for ref property, if then replace old value with new one
         if (keys === "$ref") {
-					if (document[keys].includes(oldValue)) {
+          if (document[keys].includes(oldValue)) {
             let keyValue = document[keys].replace(oldValue, newValue);
             document[keys] = keyValue;
-					}
+          }
         }
       }
     }
-	}
-	return document;
+  }
+  return document;
 }
 
 function mergeDocument(leftDoc, rightDoc) {
-
-	const mergedPaths = { ...leftDoc.paths, ...rightDoc.paths };
-	const mergedSchemas = { ...leftDoc.components.schemas, ...rightDoc.components.schemas };
-	const mergedParameters = { ...leftDoc.components.parameters, ...rightDoc.components.parameters };
-	const mergedTags = Array.from(new Set(leftDoc.tags.concat(rightDoc.tags)));
-	const mergedRequestBodies = { ...leftDoc.components.requestBodies, ...rightDoc.components.requestBodies };
-	const mergedResponses = { ...leftDoc.components.responses, ...rightDoc.components.responses };
-	const mergedHeaders = { ...leftDoc.components.headers, ...rightDoc.components.headers };
-
-	leftDoc.paths = mergedPaths;
-	leftDoc.components.schemas = mergedSchemas;
-	leftDoc.components.parameters = mergedParameters;
-	leftDoc.tags = mergedTags;
-	leftDoc.components.requestBodies = mergedRequestBodies;
-	leftDoc.components.responses = mergedResponses;
-	leftDoc.components.headers = mergedHeaders;
-
-	return leftDoc;
+  // not overriding: info, externalDocs (always from first file)
+  // not merging: servers, webhooks, security
+
+  // paths
+  const mergedPaths = { ...leftDoc.paths, ...rightDoc.paths };
+  leftDoc.paths = mergedPaths;
+
+  // components
+  const mergedSchemas = { ...leftDoc.components.schemas, ...rightDoc.components.schemas };
+  const mergedResponses = { ...leftDoc.components.responses, ...rightDoc.components.responses };
+  const mergedParameters = { ...leftDoc.components.parameters, ...rightDoc.components.parameters };
+  const mergedExamples = { ...leftDoc.components.examples, ...rightDoc.components.examples };
+  const mergedRequestBodies = { ...leftDoc.components.requestBodies, ...rightDoc.components.requestBodies };
+  const mergedHeaders = { ...leftDoc.components.headers, ...rightDoc.components.headers };
+  const mergedSecuritySchemes = { ...leftDoc.components.securitySchemes, ...rightDoc.components.securitySchemes };
+  const mergedLinks = { ...leftDoc.components.links, ...rightDoc.components.links };
+  const mergedCallbacks = { ...leftDoc.components.callbacks, ...rightDoc.components.callbacks };
+  leftDoc.components.schemas = mergedSchemas;
+  leftDoc.components.responses = mergedResponses;
+  leftDoc.components.parameters = mergedParameters;
+  leftDoc.components.examples = mergedExamples;
+  leftDoc.components.requestBodies = mergedRequestBodies;
+  leftDoc.components.headers = mergedHeaders;
+  leftDoc.components.securitySchemes = mergedSecuritySchemes;
+  leftDoc.components.links = mergedLinks;
+  leftDoc.components.callbacks = mergedCallbacks;
+
+  // tags
+  const mergedTags = Array.from(new Set(leftDoc.tags.concat(rightDoc.tags)));
+  leftDoc.tags = mergedTags;
+
+  return leftDoc;
 }
 
 exports.merge = merge;

package/bin/oasg

@@ -12,11 +12,12 @@ const commandExistsSync = require('command-exists').sync;
 const express = require('express');
 const swaggerUi = require('swagger-ui-express');
 const expressHttpProxy = require('express-http-proxy');
-
 const { exit } = require('process');
-const { execSync } = require('child_process');
+
+const { exec } = require(`${__dirname}/exec.js`);
 const { merge } = require(`${__dirname}/merger.js`);
 const { applyOverrides } = require(`${__dirname}/overrider.js`);
+const { openApiTarget } = require(`${__dirname}/openapi-target.js`);
 
 let VERSION = JSON.parse(fs.readFileSync('package.json')).version;
 
@@ -60,6 +61,7 @@ const DEFAULT_GENERATOR_ID_MAPPING = {
   "python": 'python',
   "contract-testing": 'typescript-node',
   "nestjs": 'typescript-angular',
+  "openapi": undefined,
 }
 
 let config;
@@ -424,6 +426,13 @@ async function generate(argv) {
 
   targetIds.forEach(targetId => {
     const target = config.targets.find(t => t.id === targetId);
+
+    // handle docs target
+    if (target.type === 'openapi') {
+      openApiTarget(target, sources[target.source], VERSION);
+      return;
+    }
+
     const binary = fetchBinary(target);
     let formatter;
 
@@ -450,6 +459,13 @@ async function publish(argv) {
 
   targetIds.forEach(targetId => {
     const target = config.targets.find(t => t.id === targetId);
+
+    // handle docs target
+    if (target.type === 'openapi') {
+      console.log('publishing need to be implemented manuallly for `openapi` targets');
+      return;
+    }
+
     const binary = fetchBinary(target);
     let formatter;
 
@@ -621,14 +637,3 @@ function determineArtifactVersion(argv) {
 function determinePreRelease(argv) {
   return argv.preRelease ? true : false;
 }
-
-// execute command
-function exec(command) {
-  try {
-    execSync(command, { stdio: 'inherit' });
-  }
-  catch (e) {
-    console.error(e.message);
-    exit(1);
-  }
-}

package/bin/openapi-target.js

@@ -0,0 +1,65 @@
+const fs = require('fs');
+const SwaggerParser = require("@apidevtools/swagger-parser");
+
+const { dump } = require(`${__dirname}/dump.js`);
+const { exec } = require(`${__dirname}/exec.js`);
+
+async function openApiTarget(target, source, version) {
+  const outDir = `out/${target.id}`;
+  let outFile = target.fileName || `openapi.yaml`;
+  outFile = `${outDir}/${outFile}`;
+
+  if (fs.existsSync(outDir)) {
+    fs.rmdirSync(outDir, { recursive: true })
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // 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');
+    console.log(`bundled specification`);
+  }
+
+  // parse document
+  let document = await SwaggerParser.parse(bundle ? outFile : source);
+
+  // set version of target document
+  document.info.version = version;
+
+  // sort schemas alphabeticaly
+  const sortSchemas = target.sortSchemas === undefined || target.sortSchemas;
+  if (sortSchemas) {
+    document.components.schemas = Object.keys(document.components.schemas)
+      .sort()
+      .reduce((obj, key) => { obj[key] = document.components.schemas[key]; return obj; }, {});
+  }
+
+  // apply custom decorators
+  const decorators = target.decorators || [];
+  decorators.forEach(d => {
+    const decoratorFile = `${d}.js`;
+    const decoratorPath = `${process.cwd()}/${decoratorFile}`;
+
+    if (!fs.existsSync(decoratorPath)) {
+      console.error(`skipped decorator '${decoratorFile}' - file does not exist`);
+      return;
+    }
+
+    const decorator = require(decoratorPath);
+
+    if (!decorator.decorate) {
+      console.error(`skipped decorator '${decoratorFile}' - must export a 'decorate(document)' function`);
+      return;
+    }
+
+    document = decorator.decorate(document);
+
+    console.log(`applied decorator '${decoratorFile}'`);
+  });
+
+  // write file
+  dump(document, outFile);
+}
+
+exports.openApiTarget = openApiTarget;

package/bin/overrider.js

@@ -1,8 +1,9 @@
 const crypto = require('crypto');
 const fs = require('fs');
-const YAML = require('yamljs');
 const SwaggerParser = require("@apidevtools/swagger-parser");
 
+const { dump } = require(`${__dirname}/dump.js`);
+
 async function applyOverrides(source, file) {
 	if (!source.overrides) {
 		return file;
@@ -54,9 +55,7 @@ async function applyOverrides(source, file) {
 		document.info.license = overrides.license;
 	}
 
-	const content = YAML.dump(document);
-
-	fs.writeFileSync(outFile, content);
+	dump(document, outFile);
 
 	return outFile;
 }

package/config.schema.yml

@@ -21,6 +21,7 @@ properties:
         - $ref: '#/targets/Python'
         - $ref: '#/targets/ContractTesting'
         - $ref: '#/targets/NestJS'
+        - $ref: '#/targets/OpenAPI'
 required:
   - targets
 additionalProperties: false
@@ -285,6 +286,23 @@ targets:
           - packageName
           - repository
 
+  OpenAPI:
+    allOf:
+      - $ref: '#/targets/Base'
+      - properties:
+          type:
+            pattern: "^openapi$"
+          fileName:
+            type: string
+          bundle:
+            type: boolean
+          sortSchemas:
+            type: boolean
+          decorators:
+            type: array
+            items:
+              type: string
+
 definitions:
   # default
   SourceOverrides:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-supercharge/oasg",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them",
   "author": "Supercharge",
   "license": "MIT",
@@ -15,12 +15,14 @@
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.0.6",
     "@apidevtools/swagger-parser": "^10.0.2",
+    "@redocly/cli": "^1.0.0-beta.123",
     "@stoplight/prism-cli": "^4.1.0",
     "@stoplight/spectral": "5.9.0",
     "ajv": "^8.11.0",
     "command-exists": "^1.2.9",
     "express": "^4.17.1",
     "express-http-proxy": "^1.6.2",
+    "js-yaml": "^4.1.0",
     "json-schema-merge-allof": "^0.7.0",
     "openapi-types": "^7.0.1",
     "openapi-typescript-validator-ext-ref": "^3.2.0-external-ref-support",