Add configuration. Store output paths and metadata in /data. Refactors and simplifying module and function names.

Author: jstirnaman

.gitignore

@@ -10,8 +10,8 @@ node_modules
 .hugo_build.lock
 /content/influxdb/*/api/**/*.html
 /api-docs/redoc-static.html*
+/data/api*
 /content/influxdb/*/api/**
-/static/openapi
 .vscode/*
 .idea
 **/config.toml

api-docs/scripts/generate-openapi-articles.js

@@ -1,7 +1,7 @@
 const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
-const openapiPathsToHugo = require('./openapi-paths-to-hugo-data/index.js');
+const openapiDocs = require('./openapi-docs/index.js');
 
 // Calculate the relative paths
 const DOCS_ROOT = '.';
@@ -24,7 +24,7 @@ function generateDataFromOpenAPI(specFile, dataOutPath, articleOutPath) {
     fs.mkdirSync(dataOutPath, { recursive: true });
   }
 
-  openapiPathsToHugo.generateHugoData({
+  openapiDocs.openapiToData({
     dataOutPath,
     articleOutPath,
     specFile
@@ -54,27 +54,33 @@ const generatePagesFromArticleData = async (articlesPath, contentPath) => {
   )
 }
 
-const api_reference_paths = {
-  'cloud-v2': {
-    spec_file: path.join(API_DOCS_ROOT, '/cloud/v2/ref.yml'),
-    pages_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2'),
-  },
-  'oss-v2': {
-    spec_file: path.join(API_DOCS_ROOT, '/v2/ref.yml'),
-    pages_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2'),
-  }
+// To output to a public folder where JavaScript can access it, use /static/<namespace>--for example: /static/openapi/
+const config = {
+  dataOutPath: path.join(DOCS_ROOT, '/data/api/influxdb'),
+  metadataOutPath: path.join(DOCS_ROOT, `/data/api-metadata/influxdb`),
+  apis: [
+    {
+      name: 'cloud-v2',
+      spec_file: path.join(API_DOCS_ROOT, '/cloud/v2/ref.yml'),
+      pages_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2'),
+    },
+    {
+      name: 'oss-v2',
+      spec_file: path.join(API_DOCS_ROOT, '/v2/ref.yml'),
+      pages_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2'),
+    }
+  ]
 }
 
-Object.keys(api_reference_paths).forEach((key) => {
-  const api = api_reference_paths[key];
-  const staticPath = path.join(DOCS_ROOT, '/static/openapi');
-  const staticSpecPath = path.join(staticPath, `/influxdb-${key}.yml`);
-  const staticPathsPath = path.join(staticPath, `/influxdb-${key}/paths`);
-  const articlesPath = path.join(DOCS_ROOT, `/data/article-data/influxdb/${key}`);
+config.apis.forEach(api => {
   // Execute the getswagger.sh script
-  execCommand(`${path.join(API_DOCS_ROOT, 'getswagger.sh')} ${key} -B`);
-  // Copy the generated OpenAPI spec to the static folder
-  fs.copyFileSync(api.spec_file, staticSpecPath);
-  generateDataFromOpenAPI(api.spec_file, staticPathsPath, articlesPath);
-  generatePagesFromArticleData(articlesPath, api.pages_dir);
+  execCommand(`${path.join(API_DOCS_ROOT, 'getswagger.sh')} ${api.name} -B`);
+  const dataOut = path.join(config.dataOutPath, api.name);
+  const metadataOut = path.join(config.metadataOutPath, api.name);
+  if (!fs.existsSync(dataOut)) {
+    fs.mkdirSync(dataOut, { recursive: true });
+  }
+  fs.copyFileSync(api.spec_file, path.join(dataOut, api.name + '.yml'));
+  generateDataFromOpenAPI(api.spec_file, dataOut, metadataOut);
+  generatePagesFromArticleData(metadataOut, api.pages_dir);
 });

api-docs/scripts/openapi-paths-to-hugo-data/cli.js renamed to api-docs/scripts/openapi-docs/cli.js

@@ -1,15 +1,14 @@
-const path = require('path');
 const argparse = require('argparse');
-const openapiPathsToHugo = require('./index.js');
+const apiDocs = require('./index.js');
 
 const cli = new argparse.ArgumentParser({
-  prog:  'openapi-docs',
+  prog:  'api-docs',
   add_help: true
 });
 
 cli.add_argument('--hugo', {
-  help:   'Generate Hugo data from OpenAPI paths',
-  dest:   'generateHugoData'
+  help:   'Generate a data file with objects (e.g. for Hugo data) from OpenAPI paths',
+  dest:   'generateData'
 });
 
 cli.add_argument('-d', '--data-output', {
@@ -42,12 +41,12 @@ var options = cli.parse_args();
 
 /* Usage examples
  * 
- node ./openapi-paths-to-hugo-data/index.js \
+ node ./api-docs-data/index.js \
   ./data/influxdb/cloud/openapi.yaml \
   -d ./data/influxdb/cloud/path-apis \
   -o ./data/article-data/influxdb/cloud
 
- node ./openapi-paths-to-hugo-data/index.js \
+ node ./api-docs-data/index.js \
    ./data/influxdb/oss/openapi.yaml \
    -d ./data/influxdb/oss/path-apis \
    -o ./data/article-data/influxdb/oss
@@ -57,6 +56,6 @@ var options = cli.parse_args();
 ////////////////////////////////////////////////////////////////////////////////
 
 
-if (options.generateHugoData) {
-  openapiPathsToHugo.generateHugoData(options);
+if (options.generateData) {
+  apiDocs.openapiToData(options);
 }

api-docs/scripts/openapi-paths-to-hugo-data/index.js renamed to api-docs/scripts/openapi-docs/index.js

@@ -18,7 +18,7 @@ const openapiUtils = {
   }
 }
 
-function writePathOpenapis(openapi, prefix, outPath) {
+function openapiPaths(openapi, prefix, outPath) {
   const pathGroups = {};
   Object.keys(openapi.paths).sort()
   .forEach((p) => {
@@ -84,7 +84,7 @@ function createArticleDataForPathGroup(openapi) {
   return article;
 }
 
-function writeOpenapiArticleData(sourcePath, targetPath, opts) {
+function openapiMetadata(sourcePath, targetPath, opts) {
   const isFile = filePath => {
     return fs.lstatSync(filePath).isFile();
   };
@@ -117,17 +117,20 @@ function writeOpenapiArticleData(sourcePath, targetPath, opts) {
   }
 }
 
-function generateHugoData(options) {
+function openapiToData(options) {
   const filenamePrefix = `${path.parse(options.specFile).name}-`;
 
   const sourceFile = readFile(options.specFile, 'utf8');
   console.log(`Generating OpenAPI path files in ${options.dataOutPath}....`);
-  writePathOpenapis(sourceFile, filenamePrefix, options.dataOutPath);
+  openapiPaths(sourceFile, filenamePrefix, options.dataOutPath);
 
   console.log(`Generating OpenAPI article data in ${options.articleOutPath}...`);
-  writeOpenapiArticleData(options.dataOutPath, options.articleOutPath, {filePattern: filenamePrefix});
+  openapiMetadata(options.dataOutPath, options.articleOutPath, {filePattern: filenamePrefix});
 }
 
 module.exports = {
-  generateHugoData
+  openapiToData,
+  openapiPaths,
+  openapiMetadata
+
 };

api-docs/scripts/openapi-paths-to-hugo-data/package.json renamed to api-docs/scripts/openapi-docs/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "openapi-paths-to-hugo-data",
+  "name": "api-docs-data",
   "version": "1.0.0",
   "description": "A tool to convert OpenAPI v3 paths to Hugo data.",
   "main": "index.js",