[](https://travis-ci.org/ga4gh/gh-openapi-docs) [](https://cove
npm install gh-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.
---
Install command-line dependencies:
``shell`
npm install -g @redocly/openapi-cli && npm install -g redoc-cli
Install CLI:
`shell`
npm install -g @ga4gh/gh-openapi-docs
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).
`json`
{
"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., )docsRoot
+ : folder dirname and path for where rendered outputs are to be stored | default: "docs" (i.e., or 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/, whereas all content for all other branches will be hosted at https://ga4gh.github.io/ | default: "master"
+ : name used for the folder where content for any non-default branches will be stored and hosted | default: "preview"
This package is designed to create artifacts in the following path(s):
- {branchPath}/docs/index.html
-
-
Where branchPath is the repo root if the current branch is defaultBranch (typically master), otherwise preview/.
Note: OpenAPI specs for testing can be found at test/test-spec/combined/openapi.yaml and test/test-spec/split/openapi.yaml.
Run the command...
`shell`
gh-openapi-docs
You should see console logs that look like this:
`shell
Preparing docs for API spec at 'openapi/openapi.yaml' (develop)
Cloning 'gh-pages' branch into '
Branch folder:
API spec (root) location:
Bundling API spec...
Storing bundled 'openapi.json' and 'openapi.yaml' in:
Generating standalone ReDoc HTML:
Done (in 5s.)
``