Document API with OpenAPI (Swagger)

[nhoening]

We document the API endpoints via Sphinx, but it would be much more developer-friendly to do that with the OpenAPI standard.

Our preferred way is to use ApiSpec to generate the endpoint specs (via YAML), as that might be saving a lot of work in describing what goes in and out (via Marshmallow). We've started using Marshmallow since API version 3 (and earlier versions are deprecated by now).

In any case, the existing endpoints docstrings should be straightforward to turn into OpenAPI YAML as they are now (without specific in-and-out specs), which ApiSpec will probably also eat.

So via ApiSpec for all endpoints we should get to a swagger.json file, which we'd host as a static resource.

Finally, we can use Flask-Swagger-UI so that each FlexMeasures instance hosts its own API documentation.

My open architectural questions are:

• Ideally, we would still include endpoint documentation in the official FlexMeasures API. Shpinx supports OpenAPI, so that should not be a huge problem.
• does every FM API version host their own OpenAPI documentation via a Swagger UI? I assume yes, to support every third-party developer. It could also be only the latest, with a note for each endpoint since when it is supported, but that might leave out implementation details of earlier versions. The FlexMeasures UI might need to link to these API docs (as it should also link to our Sphinx docs).
• We can look into using an API framework instead of bare-bones MethodView. Then this one and this one would be interesting. We already use the important ingredients (Marshmallow, webargs, and ApiSpec is also by the same group of people). But using one of these could also lead to other troubles, shoehorning what we do into their way.