This folder contains the sources of rportd API documentation following the openapi 3.0.1 standard.
If you came by here to read the API documentation go to apidoc.rport.io to switch to the rendered HTML version. For those preferring swagger-style rendering, use this link
There a many tools out there to convert the yaml sources into different formats. For example Swagger Codegen or the Open API Codegenerator. Both are java command line tools.
More comfort for reading and writing Open API docs is provided by Redoc and there command line tool Redoc CLI.
With NodeJS installed you can directly launch the tools with npx
. See below.
Running a local webserver is very handy for writing the documentation. Changes to the files are immediately rendered.
cd ./api-doc/openapi
npx @redocly/cli preview-docs openapi.yaml
Before pushing changes to the repository verify the linter does not throw errors.
cd ./api-doc/openapi
npx @redocly/cli lint openapi.yaml
Details about the applied rules and there output can be found here
The linter is integrated into the GitHubWorkflow and merge request are rejected if the linter throws errors or warnings.
To render the API documentation into a single dependency-free html file use:
npx redoc-cli build -o index.html openapi.yaml