add modules to create redoc UI; reorganize and clean up code

.gitignore

@@ -108,6 +108,7 @@ dist
 
 # Documentation build system artifacts
 swagger-ui
+redoc-ui
 shared
 swagger.*
 build

.spec-docs.json.sample

@@ -0,0 +1,4 @@
+{
+    "apiSpecPath": "test/test-spec/combined/openapi.yaml",
+    "contactUrl": ""
+}

README.md

@@ -1 +1,97 @@
 # gh-schema-docs
+
+## Installation
+
+After cloning this repo...
+
+```shell
+npm install -g . && npm install -g swagger-repo
+```
+
+## Set up
+
+Within a repo directory that contains an OpenAPI spec, create a config file named `.spec-docs.json` with the relative path to your spec:
+
+```json
+{
+    "apiSpecPath": "openapi/swagger.yaml",
+    "contactUrl": ""
+}
+```
+
+## Outputs
+
+This package is designed to create artifacts in the following locations:
+
+- `{branchPath}/docs/` (not currently implemented; might be replaced by ReDoc)
+- `{branchPath}/swagger-ui/` (might be replaced by ReDoc)
+- `{branchPath}/redoc-ui/` (not currently implemented)
+- `shared/` (common assets to use for Swagger UI; might be irrelevant with switch to ReDoc)
+
+Where `branchPath` is the repo root if the current branch is `master`, otherwise `preview/<branchName>`.
+
+## Usage
+
+Run the command...
+
+```shell
+cloud-schema-docs
+```
+
+You should see console logs that look like this:
+
+```shell
+{ apiSpecPath: 'openapi/swagger.yaml',
+  docsRoot: 'docs',
+  uiRoot: 'swagger-ui',
+  redocRoot: 'redoc-ui',
+  defaultBranch: 'master',
+  branchPathBase: 'preview',
+  contactUrl: '',
+  sha: '<commit-sha>',
+  abbreviatedSha: '<abbreviated-commit-sha>',
+  branch: 'develop',
+  tag: null,
+  committer: null,
+  committerDate: null,
+  author: null,
+  authorDate: null,
+  commitMessage: null,
+  root:
+   '<repo-path>',
+  commonGitDir:
+   '<repo-path>/.git',
+  worktreeGitDir:
+   '<repo-path>/.git',
+  lastTag: null,
+  commitsSinceLastTag: Infinity,
+  env: undefined,
+  repoOrigin:
+   'https://github.com/<gh-org>/<repo-name>',
+  branchPath:
+   '<repo-path>/preview/develop' }
+
+Preparing docs for API spec at 'openapi/swagger.yaml' (develop)
+Cloning 'gh-pages' branch into '<repo-path>/.ghpages-tmp'
+Cloning into '.'...
+
+...
+
+Bundling API spec...
+
+> <repo-name>-openapi-spec@1.0.0 swagger <repo-path>
+> swagger-repo "bundle" "-o" "<repo-path>/preview/develop/openapi.json"
+
+Created "<repo-path>/preview/develop/openapi.json" openapi file.
+
+> <repo-name>-openapi-spec@1.0.0 swagger <repo-path>
+> swagger-repo "bundle" "--yaml" "-o" "<repo-path>/preview/develop/openapi.yaml"
+
+Created "<repo-path>/preview/develop/openapi.yaml" openapi file.
+Copying Swagger UI index to '<repo-path>/preview/develop/swagger-ui'
+Swagger UI folder contents:
+index.html
+
+Updating API spec path for '<repo-path>/preview/develop/swagger-ui/index.html'
+Done (in 6s.)
+```

bin/cloud-schema-docs.js

@@ -3,7 +3,7 @@
 const updater = require('update-notifier');
 const parseArgs = require('yargs-parser');
 const pkg = require('../package.json');
-const release = require('../src');
+const release = require('../lib');
 
 const aliases = {
   c: 'config',

lib/bundle.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+const shell = require('shelljs');
+const path = require('path');
+const config = require('./config');
+const Log = require('./log');
+const $RefParser = require("json-schema-ref-parser");
+let YAML = $RefParser.YAML;
+
+const log = new Log();
+
+var SWAGGER_JSON_PATH = path.join(config.branchPath, 'openapi.json');
+var SWAGGER_YAML_PATH = path.join(config.branchPath, 'openapi.yaml');
+
+const bundleSpec = async function() {
+    shell.mkdir('-p', 'spec');
+    // shell.mkdir('-p', 'web_deploy');
+
+    var specPath = path.join(config.root, config.apiSpecPath);
+    var baseDir = path.dirname(specPath);
+    // shell.cp('-r', `${baseDir}/*`, 'spec');
+    shell.cp(specPath, 'spec/openapi.yaml');
+
+    log.log("\nBundling API spec...");
+    // try {
+    //     let schema = await $RefParser.bundle(specPath);
+    //     // console.log(schema);
+    //     console.log(YAML.stringify(schema.paths['/echo'].post.responses['200'].headers['X-Expires-After']));
+    // }
+    //     catch(err) {
+    //     console.error(err);
+    // }
+    shell.exec(
+        `npm run swagger bundle --        -o ${SWAGGER_JSON_PATH}`
+    );
+    shell.exec(
+        `npm run swagger bundle -- --yaml -o ${SWAGGER_YAML_PATH}`
+    );
+    shell.rm('-rf', 'spec');
+};
+
+// bundleSpec()
+module.exports.bundleSpec = bundleSpec;

src/config.js → lib/config.js

@@ -10,6 +10,7 @@ localConfig = {
   apiSpecPath: userConfig.apiSpecPath || '',
   docsRoot: userConfig.docsRoot || 'docs',
   uiRoot: userConfig.uiRoot || 'swagger-ui',
+  redocRoot: userConfig.redocRoot || 'redoc-ui',
   defaultBranch: userConfig.defaultBranch || 'master',
   branchPathBase: userConfig.branchPath || 'preview',
   contactUrl: userConfig.contactUrl || ''

src/gh-pages.js → lib/gh-pages.js

@@ -16,9 +16,11 @@ const fetchPages = function() {
     shell.exec(`git clone --depth=1 --branch=gh-pages ${config.repoOrigin} .`);
     shell.cp('-Rn', '.', config.root)
     shell.cd(startDir);
-    // rm('-rf', '.ghpages-tmp')
+    rm('-rf', '.ghpages-tmp')
 };
 
+// TODO: add logic to move all rendered artifacts to correct location
+// prior to gh-pages deploy
 const stagePages = function() {
     if (config.branch != 'gh-pages' ) {
 
@@ -31,7 +33,7 @@ const stagePages = function() {
     }
 }
 
-stagePages()
+// stagePages()
 module.exports.fetchPages = fetchPages;
 module.exports.stagePages = stagePages;
 

lib/redoc-ui.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+'use strict';
+const shell = require('shelljs');
+const path = require('path');
+const config = require('./config');
+const Log = require('./log');
+
+const log = new Log();
+
+var SHARED_UI_PATH = path.join(config.root, 'shared', config.redocRoot);
+var SWAGGER_YAML_PATH = path.join(config.branchPath, 'swagger.yaml');
+
+const getAssets = function() {
+    shell.rm('-rf', SHARED_UI_PATH);
+    shell.mkdir('-p', SHARED_UI_PATH);
+};
+
+const setupUI = function() {
+    getAssets()
+    var uiPath = path.join(config.branchPath, config.redocRoot);
+    shell.mkdir('-p', uiPath);
+    var indexPath = path.join(uiPath, 'index.html');
+    log.log(`Generating ReDoc UI index at '${indexPath}'`);
+    shell.exec(
+        `npm run redoc -- ${SWAGGER_YAML_PATH} --output ${indexPath}`
+    );
+    log.preview({
+        'title': 'ReDoc UI folder contents',
+        'text': shell.ls(uiPath).stdout
+    });
+};
+
+// setupUI()
+module.exports.getAssets = getAssets;
+module.exports.setupUI = setupUI;

src/swagger-ui.js → lib/swagger-ui.js

@@ -9,7 +9,7 @@ const log = new Log();
 
 var SWAGGER_UI_DIST = require("swagger-ui-dist").getAbsoluteFSPath();
 var SHARED_UI_PATH = path.join(config.root, 'shared', config.uiRoot);
-var SWAGGER_JSON_PATH = path.join(config.branchPath, 'swagger.json');
+var SWAGGER_JSON_PATH = path.join(config.branchPath, 'openapi.json');
 
 const getAssets = function() {
     shell.rm('-rf', SHARED_UI_PATH);
@@ -43,6 +43,6 @@ const setupUI = function() {
     );
 };
 
-setupUI()
+// setupUI()
 module.exports.getAssets = getAssets;
 module.exports.setupUI = setupUI;

src/tasks.js → lib/tasks.js

@@ -2,9 +2,11 @@ const _ = require('lodash');
 const Logger = require('./log');
 const Config = require('./config');
 const { fetchPages } = require('./gh-pages');
+const { bundleSpec } = require('./bundle');
+// TODO: switch to setupUI exported from redoc-ui
 const { setupUI } = require('./swagger-ui');
 
-const runTasks = async (opts, di) => {
+const runTasks = function(opts, di) {
   let container = {};
 
   try {
@@ -16,8 +18,9 @@ const runTasks = async (opts, di) => {
 
     console.log(container.config);
     log.obtrusive(`Preparing docs for API spec at '${container.config.apiSpecPath}' (${container.config.branch})`);
-    await fetchPages();
-    await setupUI();
+    fetchPages();
+    bundleSpec();
+    setupUI();
 
     log.log(`Done (in ${Math.floor(process.uptime())}s.)`);