The existing openapi spec document (used to generate the swagger
ui page in the web app as well as the rst documentation) is
both incomplete and wrong due to bitrot.
This change adds a script which automatically generates much of
the api documentation from the code. The output is still incomplete,
but it does include at least the same endpoints currently documented,
and of those, all of the inputs and outputs.
Due to its automatic generation, all of the endpoints and their
inputs are now documented. Only some outputs are missing (as well
as explanatory text, which was pretty thin before).
It does the following:
* Inspects the cherrypy router object to determine the endpoints to
include, and identifies their HTTP methods and the python functions
that implement them.
* It inspects the function python docstring to get summary documentation
for the endpoint.
* It inspects the function arguments and compares them to the
router path to determine if each is a path or query parameter,
as well as whether each is required.
* It merges type and descriptive information from the python docstring
about each parameter.
* For output, a schema system similar to voluptuous is used to describe
the output names and types, as well as optional descriptive information.
One of two function decorators are used to describe the output.
It removes the documentation for the status page output format. This API
is specially optimized for the Zuul status page, is very complex, and we
should therefore not encourage end-users to develop against it. The
endpoint itself is documented as such, but the response value is
undocumented.
Future work:
More descriptive text and output formats can be documented.
Change-Id: Ib1a2aad728c4a7900841a8e3b617c146f2224953
9105ffe00b