Skip to content

Files

Latest commit

Aug 21, 2023
4d9f523 · Aug 21, 2023

History

History
This branch is 1767 commits ahead of ntv-one/rport:master.

api-doc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Aug 21, 2023
Mar 23, 2023

API Documentation

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

Build the documentation from the sources

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.

Run a local webserver

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

Use the linter

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.

Render to HTML

To render the API documentation into a single dependency-free html file use:

npx redoc-cli build -o index.html openapi.yaml