Generate Swagger API declaration

[Natim]

We talked about it at Djangocong, it would be really good to add automatic functional tests and documentation.

Refs mozilla-services/cliquet#257

[almet]

Related to https://wiki.mozilla.org/Outreachy#Add_support_for_OpenAPI_to_Kinto

[Natim]

Yes it is 💃

[leplatrem]

https://larlet.fr/david/blog/2016/specifications-apis/

[leplatrem]

Some notes/ideas:

Instead of generating the Swagger from the source code, which seems very hard based on the services definitions only. We could edit it by hand and then make sure it remains up-to-date with a plugin like pyramid-swagger

Editing it by hand can be tedious in our case since we have many properties that are repeated accross the API.

We can imagine to edit by hand several small pieces of yaml/json and have a way to assemble them towards a final big spec file. Also, depending on settings or what plugins are installed the list of endpoints may change... I wonder how that should come into play.