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 and auth controllers as a demo. As you can see 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).
You can preview it here: https://www.qbittorrent.org/openapi-demo/

[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.

[rmartin16]

👍🏼 I definitely support this. My process has depended on reading the code to understand the API signatures. This should also help make finding differences among versions much easier. This obviously all depends on keeping the spec up-to-date; fortunately, I am able to automatically create one for the Python interface.

[sledgehammer999]

You can now preview the OpenAPI spec in the browser: https://www.qbittorrent.org/openapi-demo/
I have pushed some yaml restructuring to give more helpful hints to anyone who wants to edit the spec.
Now each API "controller" is documented in its yaml file which is referenced by the main yaml file.