gh-openapi-docs

GitHub OpenAPI Docs

The gh-openapi-docs package can be used to build ReDoc API documentation for an OpenAPI specification (no server implementation required) and host on GitHub Pages. Some features and configuration are slightly opinionated, based on experiences developing standard APIs with the Global Alliance for Genomics & Health (GA4GH), but should be generalizable to most repos working with Swagger/OpenAPI.

Note: this package is intended to be used with an existing repo via a config file and continuous integration. To install and run locally, refer to the steps below.

This project was heavily bootstrapped with outstanding products from the Redoc.ly team:

• redoc - OpenAPI/Swagger-generated API Reference Documentation
• openapi-cli - OpenAPI 3 CLI toolbox with rich validation and bundling features
• with additional inspiration and examples from create-openapi-repo

An additional shoutout to redoc-editor from @pointnet, which was greatly helpful in designing a GA4GH-specific theme.

---

Installation

Install command-line dependencies:

npm install -g @redocly/openapi-cli && npm install -g redoc-cli

Install CLI:

npm install -g @ga4gh/gh-openapi-docs

Configuration

You should add a file named .spec-docs.json to the top level of your repo. The following parameters can currently be configured to modify the behavior of the gh-openapi-docs build; however, I recommend leaving the defaults for everything except apiSpecPath (which will be specific to how and where you've stored the root OpenAPI file).

{
    "apiSpecPath": "openapi/openapi.yaml",
    "docsRoot": "docs",
    "defaultBranch": "master",
    "branchPathBase": "preview"
}

• apiSpecPath: relative path to the OpenAPI spec root file | default: "openapi/openapi.yaml" (i.e., <repoRoot>/openapi/openapi.yaml)
• docsRoot: folder dirname and path for where rendered outputs are to be stored | default: "docs" (i.e., <repoRoot>/docs/ or <repoRoot>/preview/<branchName>/docs/ depending on the active branch)
• defaultBranch: the default branch, typically as defined in your GitHub settings for the repo; however, the package doesn't explicitly check these settings, so consider "default" to indicate which version is hosted at https://ga4gh.github.io/<repoName>/docs, whereas all content for all other branches will be hosted at https://ga4gh.github.io/<repoName>/preview/<branchName>/docs | default: "master"
• branchPathBase: name used for the folder where content for any non-default branches will be stored and hosted | default: "preview"

Outputs

This package is designed to create artifacts in the following path(s):

• {branchPath}/docs/index.html
• {branchPath}/openapi.json
• {branchPath}/openapi.yaml

Where branchPath is the repo root if the current branch is defaultBranch (typically master), otherwise preview/<branchName>.

Note: OpenAPI specs for testing can be found at test/test-spec/combined/openapi.yaml and test/test-spec/split/openapi.yaml.

Usage

Run the command...

gh-openapi-docs

You should see console logs that look like this:

Preparing docs for API spec at 'openapi/openapi.yaml' (develop)
 
Cloning 'gh-pages' branch into '<repo-path>/.ghpages-tmp'
 
Branch folder:
<repo-path>/preview/develop
 
API spec (root) location:
<repo-path>/openapi/openapi.yaml
 
Bundling API spec...
 
Storing bundled 'openapi.json' and 'openapi.yaml' in:
<repo-path>/preview/develop/
 
Generating standalone ReDoc HTML:
<repo-path>/preview/develop/docs/index.html
 
Done (in 5s.)