Clone wiki

rest-api-blueprint / ApiDocumentation


The following seem like a good idea:

  • Make the API documentation accessible through requests for HTML with GET on the API URLs.
  • Make the documentation interactive (able to test GETs/PUTs etc from the documentation pages).
  • Make the source material obviously linked to the code.
  • Share the source material with more general documentation tools.

The last bullet in particular suggests using Sphinx, the de facto choice and tool behind and etc.

I tried using the httpdomain sphinx extension (which includes Flask extension), but did not find it sufficiently expressive. Preferred instead to keep more flexibility.


  • Write reST in separate files
  • Tell Sphinx to compile them into Flask's static folder.
  • Run to convert the reST into HTML.
    • The examples are generated using the programoutput extension to run against the server, thus automatically ensuring accuracy. Beware that the extension caches outputs...
  • Redirect HTTP GET for text/html to the appropriate page

See apidocs for details. Beware that Bitbucket does not understand all the Sphinx directives so it is best to browse the .rst files in raw mode (or just download the repo and view locally).

See also