Switch to ReDoc for docs & UI

lib/bundle.js

@@ -4,40 +4,27 @@ 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');
+var OPENAPI_JSON_PATH = path.join(config.branchPath, 'openapi.json');
+var OPENAPI_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}`
+        `npm run swagger bundle --        -o ${OPENAPI_JSON_PATH}`
     );
     shell.exec(
-        `npm run swagger bundle -- --yaml -o ${SWAGGER_YAML_PATH}`
+        `npm run swagger bundle -- --yaml -o ${OPENAPI_YAML_PATH}`
     );
     shell.rm('-rf', 'spec');
 };
 
-// bundleSpec()
 module.exports.bundleSpec = bundleSpec;

lib/redoc-ui.js

@@ -7,29 +7,20 @@ 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);
-};
+var OPENAPI_YAML_PATH = path.join(config.branchPath, 'openapi.yaml');
 
 const setupUI = function() {
-    getAssets()
-    var uiPath = path.join(config.branchPath, config.redocRoot);
+    var uiPath = path.join(config.branchPath, config.docsRoot);
     shell.mkdir('-p', uiPath);
     var indexPath = path.join(uiPath, 'index.html');
-    log.log(`Generating ReDoc UI index at '${indexPath}'`);
+    log.log(`Generating OpenAPI docs index at '${indexPath}'`);
     shell.exec(
-        `npm run redoc -- ${SWAGGER_YAML_PATH} --output ${indexPath}`
+        `npm run redoc -- ${OPENAPI_YAML_PATH} --output ${indexPath}`
     );
     log.preview({
-        'title': 'ReDoc UI folder contents',
+        'title': 'OpenAPI docs folder contents',
         'text': shell.ls(uiPath).stdout
     });
 };
 
-// setupUI()
-module.exports.getAssets = getAssets;
 module.exports.setupUI = setupUI;

lib/tasks.js

@@ -3,8 +3,7 @@ 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 { setupUI } = require('./redoc-ui');
 
 const runTasks = function(opts, di) {
   let container = {};
@@ -18,7 +17,7 @@ const runTasks = function(opts, di) {
 
     console.log(container.config);
     log.obtrusive(`Preparing docs for API spec at '${container.config.apiSpecPath}' (${container.config.branch})`);
-    fetchPages();
+    // fetchPages();
     bundleSpec();
     setupUI();
 

test/test-spec/combined/openapi.yaml

@@ -10,7 +10,7 @@ info:
     name: Apache 2.0
     url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
   x-logo:
-    url: 'https://apis.guru/openapi-template/logo.png'
+    url: 'https://www.openapis.org/wp-content/uploads/sites/3/2018/02/OpenAPI_Logo_Pantone-1.png'
   description: >
     This is an **example** API to demonstrate features of OpenAPI specification
 
@@ -59,23 +59,26 @@ tags:
     description: Example echo operations
   - name: User
     description: Operations about user
-  - name: Motivation
+  - name: Example Chapter
     description: |
-      # Section 1
+      # Overview
+
+      Here is an example of additional context that can be added with markdown.
+
+      ## Basic syntax
+
+      You can use standard markdown tables and formatting
 
       | Tables   |      Are      |  Cool |
       |----------|:-------------:|------:|
       | col 1 is |  left-aligned | $1600 |
       | col 2 is |    centered   |   $12 |
       | col 3 is | right-aligned |    $1 |
 
+      ## Images
 
-      <img style='float: right;' width='300' src='figure1.png'/>
-      Data sharing requires portable data, consistent with the FAIR data
-      principles (findable, accessible, interoperable, reusable). Today’s
-      researchers and clinicians are surrounded by potentially useful data,
-      but often need bespoke tools and processes to work with each dataset.
-      And today’s data publishers don’t have a reliable way to make their data useful to all (and only) the people they choose."
+      <img style='float: right;' width='250' src='../../../test/test-shared/OpenAPI_Logo_Pantone-1.png'/>
+      This is a block of text arranged next to an image (hosted in this repo).
 
 servers:
   - url: 'http://example.com/api/v1'
@@ -87,7 +90,7 @@ x-tagGroups:
       - User
   - name: Appendix
     tags:
-      - Motivation
+      - Example Chapter
 paths:
   /echo:
     post: