The main documentation files are written in Markdown or MDX (also have a look at the Docusaurus-specific Markdown features). You can find the documentation files in the following folders:
docs/for the English documentation.i18n/de/docusaurus-plugin-content-docs/current/for the German documentation.
When making documentation changes, please remember to update both the English and German versions (when applicable) in the same pull request. If you are not comfortable authoring in one of these languages, feel free to still open a partial pull request and ask for help with translation.
Also, have a look at the official Docusaurus documentation on internationalization for more information.
To build this project locally, you will need to have Node.js installed. Compatible versions are declared in the engines section in the package.json file.
You can use the following commands to build this project locally:
npm installto install dependencies.npm run generateto build the OpenAPI reference.npm startto start a development server.npm run buildto build a production release (this may be necessary to work with multi-lingual content).npm run serveto serve a production release locally.
The changelog is built using Docusaurus' blog feature. You can add a new changelog entry by creating a new markdown file in the changelog/ directory. The file name should follow the pattern YYYY-MM-DD-<name>.mdx. The file should contain a frontmatter section with the following fields:
title: Example changelog entry
authors: your-name # see changelog/authors.yml
tags: [apiv2] # see changelog/tags.ymlThere is also a Gitlab CI job that will automatically create a changelog entry each day when the OpenAPI specification changed (both v1 and v2 are checked for changes). This job will create a new changelog entry in the changelog/ directory with the name YYYY-MM-DD-api-changes-vX.mdx. To track the API changes, the last OpenAPI specification is saved in the generator/specs directory, which will then be compared to the current OpenAPI specification. The comparison is done using the oasdiff tool.
To run the automatic changelog generation locally, you can run the npm run generate:changelog command. Note that the changelog generator relies on some AI features for text generation, to you will need a valid OpenAI API key in the OPENAI_API_KEY environment variable.
Automatically generated changelog entries will NOT be changed after they are created (they are identified uniquely by the date and the affected API version). This means that you (as a developer) are free to edit the automatically generated changelog entries to your liking (pay special attention to the AI-generated summary, which may or may not be correct).
Translation of components is done using Docusaurus' built-in translation file handling. To update the translation files, you can use the following steps:
$ npm run docusaurus write-translations
$ npm run docusaurus write-translations -- -l de
By default, the OpenAPI description pages use the OpenAPI .description field of the respective resource. You can override the description with a custom markdown document by placing it in generator/overlays/<apiVersion>/<operation-id>/description.md. Please note that you will need to run npm run generate for changes to take effect.
By default, the tag index pages will be generated from the tag description and an auto-generated list of all operations. You can override this index page by providing a custom markdown document at generator/overlays/<apiVersion>/<tag-name>.mdx. Please note that you will need to run npm run generate for changes to take effect.
The usage examples for OpenAPI operations are generated from the OpenAPI specification. You can override the usage examples by providing a custom markdown document at generator/overlays/<apiVersion>/<operation-id>/example-<language>.md. Please note that you will need to run npm run generate for changes to take effect. Supported languages are curl, javascript, php and cli.