RFC: API Documentation

[arikfr]

trafficstars

Redash has a very rich API, but it's undocumented[1] which makes it far less useful or adopted than it could be.

It seems that the way to go forward is to adopt something like OpenAPI (f.k.a Swagger) to generate an API spec that we can then use to create the documentation (and maybe clients as well).

In the Python/Flask ecosystem there are several libraries to help with this:

1. marshmallow -- to define schemas and serialization/deserialization of objects.
2. apispec to generate OpenAPI specs.

There are also marshmallow-sqlalchemy and several Flask/apispec libraries.

---

It will be great to get comments and ideas from others who tried these or other tools already before we start implementing this.