Rest api docs

[ael-code]

How do we want to provide docs for REST API?

I'll try to list some different options:

• we could use sphinxcontrib and the flask plugin to provide documentation through sphinx and rtfd.org
• @hellais in #52 suggests to use Swagger for documenting API. I already use it and I like this tools. We could expose Swagger-UI through flask under something like /api/docs but in this case the only way to read the API docs is to run libreant. To resolve this problem we could try some way:
  • thanks to Swagger-codegen it's also possible to generate static html docs
  • I found also sphinx-swagger that seems to convert swagger specs into sphinx docs.

What option do you like the most? Do you know other tools/ways to documenting the REST API?

[boyska]

The only solutions that seem right to me are the sphinx-based ones, that is sphinxcontrib.httpdomain and sphinx-swagger. However, I'm not totally sure that sphinx-swagger does what I think it does or what you say it does. I say so because its directive

.. swaggerurl:: URL

seems very strange; why should it get an URL just to document my endpoints? I'd like something to just generate documentation to be put inside the sphinx doc, without requiring a special "service".