Expert Python Programming - Third Edition

Documenting web APIs

The principles for documenting web APIs are almost the same as for other kinds of software. You want to properly target your readership, provide documentation in a way and form that is native for the usage environment (here, as a web page), and, most of all, make sure that readers have access to the up to date and relevant version of your documentation.

Because of this, it is extremely important to have your documentation of web APIs generated from the sources of the code that provides these APIs. Unfortunately, due to the complex architecture of most web frameworks, classical documentation tools like Sphinx are rarely useful for documenting typical HTTP endpoints of web APIs. In this context, it is very common that auto-documentation ...