Skip to content


Repository files navigation


This website is built using

  • Docusaurus 2, a modern static website generator, for the static site generation
  • Widdershins, for OpenApi spec => API reference markdown
  • OpenAPI Generator for generating the SDKs and related documentation.



  • You need node (version 12 works fine. v14 had some issues)
  • Java (Tested with OpenJDK 1.8.0_242-b08. Presumably later versions work too).
  • s3-deploy to push to AWS S3

Building the site

$ cd yat-docs
$ yarn install # npm doesn't seem to work for some reason
$ cd ../yatdocs-plugin
$ yarn install

Local Development

$ cd yat-docs
$ yarn run generate-docs # Generates the API reference and SDK docs
$ yarn start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.


$ cd yat-docs
$ yarn run generate-docs # Generates the API reference and SDK docs
$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Other commands

Usage: docusaurus <command> [options]

  -V, --version                                            output the version number
  -h, --help                                               output usage information

  build [options] [siteDir]                                Build website
  swizzle [options] [themeName] [componentName] [siteDir]  Copy the theme files into website folder for customization.
  deploy [options] [siteDir]                               Deploy website to GitHub pages
  start [options] [siteDir]                                Start the development server
  serve [options] [siteDir]                                Serve website
  docs:version <version>                                   Tag a new docs version
  clean-sdk                                                Delete all generated SDK documentation files
  generate-sdk                                             Build the SDKs and then quit
  clean-api-ref                                            Delete all generated documentation files
  generate-api-ref                                         Build the API reference documentation and then quit
  clean-docs                                               Delete all generated SDK and API reference documentation files
  generate-docs                                            Generate and save the SDK and API reference docs without building the website

Debug logs

To generate debug logs to stdout, set the `DEBUG~ environment variable. All yat-doc plugin logs are namespaced accordingly, so

$ DEBUG=yat-docs:* npm run build

will print out all yat-docs debug information and ignore any other messages from other packages.

Build and deploy

There's a makefile that eases the build / deploy cycle pain.

Make command Description
clean Deletes the build directory
cleandocs Deletes the generated docs
generate Generates the API and SDK docs
build Builds the static website
preview Build and run the site locally

To successfully deploy, you need some environment variables set up. You can store these in .env




Then run

$ ./

Generate API Key

To generate an API key that you can use as authentication in the X-Api-Key header follow these steps.

  1. Get an access token - in your browser after refreshing the page open a developer console and type JSON.parse(localStorage.getItem('tokens')).access_token
  2. Generate an API key
    curl -X POST -H 'Authorization: Bearer access_token' -H 'Content-Type: application/json' -d '{"name": "Your-Key-Name"}'
  3. The response contains an api_key field in the JSON result.
  4. All further queries can now be called with curl -H 'X-Api-Key: api_key'