clean up commands/scripts for redoc docs build

Author: jaeddy

README.md

@@ -5,7 +5,7 @@
 After cloning this repo...
 
 ```shell
-npm install -g . && npm install -g swagger-repo
+npm install -g . && npm install -g swagger-repo && npm install -g redoc-cli
 ```
 
 ## Set up
@@ -14,19 +14,20 @@ Within a repo directory that contains an OpenAPI spec, create a config file name
 
 ```json
 {
-    "apiSpecPath": "openapi/swagger.yaml",
+    "apiSpecPath": "openapi/openapi.yaml",
     "contactUrl": ""
 }
 ```
 
+**Note:** an OpenAPI spec for testing can be found at [`test/test-spec/combined/openapi.yaml`](test/test-spec/combined/openapi.yaml).
+
 ## Outputs
 
-This package is designed to create artifacts in the following locations:
+This package is designed to create artifacts in the following path(s):
 
-- `{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)
+- `{branchPath}/docs/index.html`
+- `{branchPath}/openapi.json`
+- `{branchPath}/openapi.yaml`
 
 Where `branchPath` is the repo root if the current branch is `master`, otherwise `preview/<branchName>`.
 
@@ -41,7 +42,7 @@ gh-openapi-docs
 You should see console logs that look like this:
 
 ```shell
-{ apiSpecPath: 'openapi/swagger.yaml',
+{ apiSpecPath: 'openapi/openapi.yaml',
   docsRoot: 'docs',
   uiRoot: 'swagger-ui',
   redocRoot: 'redoc-ui',
@@ -52,32 +53,34 @@ You should see console logs that look like this:
   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',
+  committer: 'James Eddy <[email protected]>',
+  committerDate: '2020-03-13T05:25:03.000Z',
+  author: 'James Eddy <[email protected]>',
+  authorDate: '2020-03-13T05:25:03.000Z',
+  commitMessage: 'replace swagger-ui and docs with redoc (for both)',
+  root: '<repo-path>',
+  commonGitDir: '<repo-path>/.git',
+  worktreeGitDir: '<repo-path>/.git',
   lastTag: null,
-  commitsSinceLastTag: Infinity,
+  commitsSinceLastTag: 0,
   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)
+Preparing docs for API spec at 'openapi/openapi.yaml' (develop)
 Cloning 'gh-pages' branch into '<repo-path>/.ghpages-tmp'
 Cloning into '.'...
-
 ...
+Branch folder:
+<repo-path>/preview/use-redoc
+Spec location:
+<repo-path>/openapi/openapi.yaml
 
 Bundling API spec...
+Storing to:
+<repo-path>/preview/develop/openapi.json
 
 > <repo-name>[email protected] swagger <repo-path>
 > swagger-repo "bundle" "-o" "<repo-path>/preview/develop/openapi.json"
@@ -88,10 +91,16 @@ Created "<repo-path>/preview/develop/openapi.json" openapi file.
 > 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:
+Generating OpenAPI docs index at '<repo-path>/preview/develop/docs/index.html'
+
+> <repo-name>[email protected] redoc <repo-path>
+> redoc-cli "bundle" "<repo-path>/preview/develop/openapi.yaml" "--output" "<repo-path>/preview/develop/docs/index.html"
+
+Prerendering docs
+
+🎉 bundled successfully in: <repo-path>/preview/use-redoc/docs/index.html (957 KiB) [⏱ 0.234s]
+OpenAPI docs folder contents:
 index.html
 
-Updating API spec path for '<repo-path>/preview/develop/swagger-ui/index.html'
-Done (in 6s.)
+Done (in 13s.)
 ```

lib/bundle.js

@@ -11,20 +11,34 @@ 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');
+    log.preview({
+        'title': 'Branch folder',
+        'text': config.branchPath
+    })
+    shell.mkdir('-p', config.branchPath);
+    var specDir = path.join(config.root, 'spec');
+    shell.mkdir('-p', specDir);
 
     var specPath = path.join(config.root, config.apiSpecPath);
-    var baseDir = path.dirname(specPath);
-    shell.cp(specPath, 'spec/openapi.yaml');
+    log.preview({
+        'title': 'Spec location',
+        'text': specPath
+    })
+    shell.cp(specPath, path.join(config.root, 'spec/openapi.yaml'));
 
     log.log("\nBundling API spec...");
+    log.preview({
+        'title': 'Storing to',
+        'text': OPENAPI_JSON_PATH
+    });
     shell.exec(
-        `npm run swagger bundle --        -o ${OPENAPI_JSON_PATH}`
+        `npm run swagger bundle --        -b ${specDir} -o ${OPENAPI_JSON_PATH}`
     );
     shell.exec(
-        `npm run swagger bundle -- --yaml -o ${OPENAPI_YAML_PATH}`
+        `npm run swagger bundle -- --yaml -b ${specDir} -o ${OPENAPI_YAML_PATH}`
     );
-    shell.rm('-rf', 'spec');
+    shell.rm('-rf', specDir);
 };
 
+bundleSpec();
 module.exports.bundleSpec = bundleSpec;

lib/gh-pages.js

@@ -16,7 +16,7 @@ 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')
+    shell.rm('-rf', '.ghpages-tmp')
 };
 
 // TODO: add logic to move all rendered artifacts to correct location

lib/redoc-ui.js

@@ -15,7 +15,7 @@ const setupUI = function() {
     var indexPath = path.join(uiPath, 'index.html');
     log.log(`Generating OpenAPI docs index at '${indexPath}'`);
     shell.exec(
-        `npm run redoc -- ${OPENAPI_YAML_PATH} --output ${indexPath}`
+        `npm run redoc bundle -- ${OPENAPI_YAML_PATH} --output ${indexPath}`
     );
     log.preview({
         'title': 'OpenAPI docs folder contents',

lib/tasks.js

@@ -17,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();
 

package.json

@@ -26,7 +26,7 @@
   "scripts": {
     "fetch": "node src/fetchpages.js",
     "swagger": "swagger-repo",
-    "redoc": "redoc-cli bundle",
+    "redoc": "redoc-cli",
     "build:swagger": "node src/swagger-ui.js",
     "build:redoc": "node src/redoc-ui.js"
   }