Split and Bundle references (#144)

* Bundle local and remote file references

* Split openAPI in files with references

Author: thim81

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## unreleased
 
+- CLI - Bundle local and remote file references
+- CLI - Split OpenAPI in a multi-file structure 
 - Add type definitions for openapi-format
 
 ## [1.23.2] - 2024-09-16

bin/__snapshots__/cli.test.js.snap

@@ -1,10 +1,9 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`openapi-format CLI command should load the default .openapiformatrc if configFile is not provided 1`] = `
+exports[`openapi-format CLI command should bundle reference 1`] = `
 "================================================================================
 OpenAPI-Format CLI settings:
-- Sort file:		(defaultSort.json)
-- Input file:		test/yaml-default/input.yaml
+- Input file:		test/yaml-ref-quotes/input.yaml
 ================================================================================
 ✅  OpenAPI formatted successfully
 ================================================================================
@@ -23,6 +22,8 @@ OpenAPI-Format CLI options:
 | sort         | false                                             |
 | keepComments | true                                              |
 | lineWidth    | -1                                                |
+| bundle       | true                                              |
+| split        | false                                             |
 | filterFile   | test/yaml-no-sort-keep-comments/customFilter.yaml |
 | verbose      | 3                                                 |
 |--------------|---------------------------------------------------|
@@ -33,6 +34,27 @@ OpenAPI-Format CLI options:
 "
 `;
 
+exports[`openapi-format CLI command should load the default .openapiformatrc if configFile is not provided 1`] = `
+"================================================================================
+OpenAPI-Format CLI settings:
+- Sort file:		(defaultSort.json)
+- Input file:		test/yaml-default/input.yaml
+================================================================================
+✅  OpenAPI formatted successfully
+================================================================================
+"
+`;
+
+exports[`openapi-format CLI command should not bundle reference 1`] = `
+"================================================================================
+OpenAPI-Format CLI settings:
+- Input file:		test/yaml-ref-quotes/input.yaml
+================================================================================
+✅  OpenAPI formatted successfully
+================================================================================
+"
+`;
+
 exports[`openapi-format CLI command should not convert large numbers in JSON 1`] = `
 "================================================================================
 OpenAPI-Format CLI settings:
@@ -71,6 +93,8 @@ Options:
   --lineWidth <lineWidth>                    max line width of YAML output (default: -1)
   --rename <oaTitle>                         overwrite the title in the OpenAPI document
   --convertTo <oaVersion>                    convert the OpenAPI document to OpenAPI version 3.1
+  --no-bundle                                Bundle the local and remote $ref in the OpenAPI document.
+  --split                                    Split the OpenAPI document into a multi-file structure. (default: false)
   --json                                     print the file to stdout as JSON
   --yaml                                     print the file to stdout as YAML
   -p, --playground                           Open config in online playground
@@ -110,6 +134,17 @@ Total components removed: 16
 "
 `;
 
+exports[`openapi-format CLI command should split the openapi file 1`] = `
+"================================================================================
+OpenAPI-Format CLI settings:
+- Input file:		../__utils__/train.yaml
+- Output location:	output.yaml
+================================================================================
+✅  OpenAPI formatted successfully
+================================================================================
+"
+`;
+
 exports[`openapi-format CLI command should stop and show error 1`] = `
 "================================================================================
 OpenAPI-Format CLI settings:
@@ -132,7 +167,7 @@ exports[`openapi-format CLI command should stop and show error about remote file
 OpenAPI-Format CLI settings:
 - Sort file:		(defaultSort.json)
 - Input file:		https://raw.githubusercontent.com/thim81/openapi-format/main/test/yaml-default/foo.yaml
-[31m Input file error - Failed to download file: 404 Not Found
+[31m Input file error - Failed to read file: 404 Not Found
 "
 `;
 
@@ -194,6 +229,8 @@ OpenAPI-Format CLI options:
 | sort         | false |
 | keepComments | false |
 | lineWidth    | -1    |
+| bundle       | true  |
+| split        | false |
 | convertTo    | 3.1   |
 | verbose      | 3     |
 |--------------|-------|

bin/cli.js

@@ -28,6 +28,8 @@ program
   .option('--lineWidth <lineWidth>', 'max line width of YAML output', -1)
   .option('--rename <oaTitle>', 'overwrite the title in the OpenAPI document')
   .option('--convertTo <oaVersion>', 'convert the OpenAPI document to OpenAPI version 3.1')
+  .option('--no-bundle', 'Bundle the local and remote $ref in the OpenAPI document.', false)
+  .option('--split', 'Split the OpenAPI document into a multi-file structure.', false)
   .option('--json', 'print the file to stdout as JSON')
   .option('--yaml', 'print the file to stdout as YAML')
   .option('-p, --playground', 'Open config in online playground')
@@ -92,13 +94,18 @@ async function run(oaFile, options) {
   configOptions = Object.assign({}, defaultOptions, configOptions);
   options.lineWidth = configOptions?.lineWidth ?? options.lineWidth;
   options.sort = configOptions?.sort ?? options.sort;
+  options.bundle = configOptions?.bundle ?? options.bundle;
 
   // Merge configOptions and CLI options
   options = Object.assign({}, configOptions, options);
   if (options['no-sort'] && options['no-sort'] === true) {
     options.sort = !options['no-sort'];
     delete options['no-sort'];
   }
+  if (options['no-bundle'] && options['no-bundle'] === true) {
+    options.bundle = !options['no-bundle'];
+    delete options['no-bundle'];
+  }
 
   // LOG - Render info table with options
   outputLogOptions = infoTable(options, options.verbose);
@@ -194,7 +201,7 @@ async function run(oaFile, options) {
   let resObj = {};
   let output = {};
   let input = {};
-  let fileOptions = {keepComments: options?.keepComments || false};
+  let fileOptions = {keepComments: options.keepComments ?? false, bundle: options.bundle ?? true};
 
   try {
     infoOut(`- Input file:\t\t${oaFile}`); // LOG - Input file
@@ -204,7 +211,7 @@ async function run(oaFile, options) {
     input = resObj;
   } catch (err) {
     if (err.code !== 'ENOENT') {
-      console.error('\x1b[31m', `Input file error - Failed to download file: ${err.message}`);
+      console.error('\x1b[31m', `Input file error - Failed to read file: ${err.message}`);
       process.exit(1);
     }
     console.error('\x1b[31m', `Input file error - Failed to read file: ${oaFile}`);
@@ -258,14 +265,27 @@ async function run(oaFile, options) {
 
   options.yamlComments = fileOptions.yamlComments || {};
   if (options.output) {
-    try {
-      // Write OpenAPI string to file
-      await openapiFormat.writeFile(options.output, resObj, options);
-      infoOut(`- Output file:\t\t${options.output}`); // LOG - config file
-    } catch (err) {
-      console.error('\x1b[31m', `Output file error - no such file or directory "${options.output}"`);
-      if (options.verbose >= 1) {
-        console.error(err);
+    if (options.split !== true) {
+      try {
+        // Write OpenAPI string to single file
+        await openapiFormat.writeFile(options.output, resObj, options);
+        infoOut(`- Output file:\t\t${options.output}`); // LOG - config file
+      } catch (err) {
+        console.error('\x1b[31m', `Output file error - no such file or directory "${options.output}"`);
+        if (options.verbose >= 1) {
+          console.error(err);
+        }
+      }
+    } else {
+      try {
+        // Write Split files
+        await openapiFormat.openapiSplit(resObj, options);
+        infoOut(`- Output location:\t${options.output}`); // LOG - config file
+      } catch (err) {
+        console.error('\x1b[31m', `Split error - no such file or directory "${options.output}"`);
+        if (options.verbose >= 1) {
+          console.error(err);
+        }
       }
     }
   } else {

bin/cli.test.js

@@ -1,7 +1,7 @@
 const testUtils = require('../test/__utils__/test-utils');
 const fs = require('fs');
 const {describe, it, expect} = require('@jest/globals');
-const {getLocalFile, getRemoteFile, parseFile} = require('../utils/file');
+const {getLocalFile} = require('../utils/file');
 
 describe('openapi-format CLI command', () => {
   it('should output the help', async () => {
@@ -191,6 +191,66 @@ describe('openapi-format CLI command', () => {
     expect(sanitize(result.stderr)).toStrictEqual(sanitize(output));
   });
 
+  it('should bundle reference', async () => {
+    const path = `test/yaml-ref-quotes`;
+    const inputFile = `${path}/input.yaml`;
+    const outputFile = `${path}/bundled.yaml`;
+    const output = await getLocalFile(outputFile);
+
+    let result = await testUtils.cli([inputFile, `--no-sort`], '.');
+    // console.log('result', result)
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('formatted successfully');
+    expect(result.stdout).toMatchSnapshot();
+    expect(sanitize(result.stderr)).toStrictEqual(sanitize(output));
+  });
+
+  it('should not bundle reference', async () => {
+    const path = `test/yaml-ref-quotes`;
+    const inputFile = `${path}/input.yaml`;
+    const outputFile = `${path}/output.yaml`;
+    const output = await getLocalFile(outputFile);
+
+    let result = await testUtils.cli([inputFile, `--no-bundle`, `--no-sort`], '.');
+    // console.log('result', result)
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('formatted successfully');
+    expect(result.stdout).toMatchSnapshot();
+    expect(sanitize(result.stderr)).toStrictEqual(sanitize(output));
+  });
+
+  it('should split the openapi file', async () => {
+    const path = `test/_split`;
+    const inputFile = `../__utils__/train.yaml`;
+    const outputFile = `output.yaml`;
+
+    const snap = await getLocalFile(`${path}/snap.yaml`);
+    const snap_station = await getLocalFile(`${path}/snap_station.yaml`);
+    const snap_station_id = await getLocalFile(`${path}/snap_station_id.yaml`);
+
+    let result = await testUtils.cli([inputFile, `--output ${outputFile}`, `--split`, `--no-sort`], path);
+
+    const outputPath = `${path}/${outputFile}`;
+    const outputStationPath = `${path}/paths/stations_{station_id}.yaml`;
+    const outputStationIdPath = `${path}/components/parameters/StationId.yaml`;
+    // const outputStationSchemaPath = `${path}/components/schemas/Station.yaml`
+    const output = await getLocalFile(outputPath);
+    const output_station = await getLocalFile(outputStationPath);
+    const output_station_id = await getLocalFile(outputStationIdPath);
+
+    // console.log('result', result)
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('formatted successfully');
+    expect(result.stdout).toMatchSnapshot();
+    expect(sanitize(output)).toStrictEqual(sanitize(snap));
+    expect(sanitize(output_station)).toStrictEqual(sanitize(snap_station));
+    expect(sanitize(output_station_id)).toStrictEqual(sanitize(snap_station_id));
+
+    fs.rmSync(`${path}/paths`, {recursive: true, force: true});
+    fs.rmSync(`${path}/components`, {recursive: true, force: true});
+    fs.unlinkSync(outputPath);
+  });
+
   it.skip('should generate a playground share URL', async () => {
     const path = `test/yaml-filter-custom`;
     const inputFile = `${path}/input.yaml`;

openapi-format.js

@@ -28,8 +28,10 @@ const {
   convertExclusiveMaximum,
   setInObject
 } = require('./utils/convert');
-const {parseFile, writeFile, stringify, detectFormat, parseString, analyzeOpenApi} = require('./utils/file');
+const {parseFile, writeFile, stringify, detectFormat, parseString, analyzeOpenApi, readFile} = require('./utils/file');
 const {parseTpl, getOperation} = require('./utils/parseTpl');
+const {writePaths, writeComponents, writeSplitOpenAPISpec} = require('./utils/split');
+const {dirname, extname} = require('node:path');
 
 /**
  * OpenAPI sort function
@@ -1015,6 +1017,31 @@ async function openapiGenerate(oaObj, options) {
   return {data: jsonObj, resultData: {}};
 }
 
+/**
+ * Split the OpenAPI document into a multi-file structure
+ * @param {object} oaObj OpenAPI document
+ * @param options
+ * @returns {Promise<void>}
+ */
+async function openapiSplit(oaObj, options = {}) {
+  if (!options.output) {
+    throw new Error('Output is required');
+  }
+
+  options.outputDir = dirname(options.output);
+  options.extension = extname(options.output).substring(1);
+
+  if (oaObj?.components) {
+    await writeComponents(oaObj.components, options);
+  }
+
+  if (oaObj?.paths) {
+    await writePaths(oaObj.paths, options);
+  }
+
+  await writeSplitOpenAPISpec(oaObj, options);
+}
+
 /**
  * OpenAPI convert version function
  * Convert OpenAPI from version 3.0 to 3.1
@@ -1118,8 +1145,10 @@ module.exports = {
   openapiGenerate: openapiGenerate,
   openapiSort: openapiSort,
   openapiChangeCase: openapiChangeCase,
+  openapiSplit: openapiSplit,
   openapiConvertVersion: openapiConvertVersion,
   openapiRename: openapiRename,
+  readFile: readFile,
   parseFile: parseFile,
   parseString: parseString,
   stringify: stringify,