WebAPI: Document API using OpenAPI

[sledgehammer999]

This is simply a demo to foster input from the community.

The process of documenting the WebAPI leaves a lot to be desired. Both in terms of actually writing down the specs and rendering them in a visually pleasing way to the end user.

The OpenAPI spec was developed for this and seems to be industry standard.
A quick guide is here.

Since it is standardized there are loads of tools that help with exploring the API, writing clients, validating, rendering documentation etc.

I am interested mainly in a) providing an easy way for others to validate their clients and b) generating helpful documentation.

I have documented the APIs of the transfer controller as a demo. I am positive that each controller can be documented in its own YAML and be referenced by the main YAML. This will help with incrementally implementing OpenAPI if we decide to go that route.

If we decide to use OpenAPI, then for each controller that is documented we will require that each PR that affects its API to also make necessary changes to the OpenAPI yaml.

The generated docs can be hooked up to be served by the mainsite (CI integration should help here).

There are many tools that generate the docs, each with its own shortfalls. Others don't explicitly show the enum values of the request, others the enum of the response, others the const value of a response. Final decision on the rendering tool will be made at later stage.

In the meantime there are two ways to view current demo:

1. Copy/paste the YAML contents into https://editor-next.swagger.io/
2. Screenshot of page rendered locally by https://github.com/Redocly/redoc
   
   
   

[Piccirello]

There are many tools that generate the docs, each with its own shortfalls. Others don't explicitly show the enum values of the request, others the enum of the response, others the const value of a response. Final decision on the rendering tool will be made at later stage.

Just to confirm, was this PR generated manually? It would be incredible to have the docs generated automatically, even if the docs weren't perfect.

[sledgehammer999]

The YAML file was created manually. Supposedly there are openapi code scanners -> yaml, but I very much doubt they will work correctly with our custom C++ server.