This is a template based on https://github.com/alphagov/tech-docs-template for publishing the OpenAPI specification for https://github.com/alphagov/digitalmarketplace-api as HTML website.

Set up requires Ruby and node.js. In the repo folder type the following to install the requrements:

make requirements

Type the following to build the HTML:

make html API_SPEC=<path/to/openapi.yaml>

This will create a build subfolder in the application folder which contains the HTML and asset files ready to be published. If make requirements has been run the build/ folder will be a worktree for the gh-pages branch.

Whilst writing documentation we can run a middleman server to preview how the published version will look in the browser.

Type the following to start the server:

make server

Note: in order to preview the changes made to the OpenAPI spec you need to rerun make html.

To rebuild and push the new version of documentation to Github Pages run

make publish API_SPEC=<path/to/openapi.yaml>