James E. Blair 9105ffe00b Add script to generate openapi spec
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

Future work:

More descriptive text and output formats can be documented.

Change-Id: Ib1a2aad728c4a7900841a8e3b617c146f2224953
2024-03-09 11:25:40 -08:00
018D05F5.gpg Avoid using apt-add-repository 2017-07-11 16:41:52 -04:00
decrypt_secret.py decrypt_secret.py: properly init SourceContext class 2021-12-17 11:35:10 -05:00
deprecated-queues.py Add a script to find deprecated queue syntax 2022-05-05 14:12:56 -07:00
docker-compose.yaml Revert "Test with MariaDB instead of MySQL" 2023-04-13 13:38:13 +00:00
encrypt_secret.py tools: Deprecate encrypt_secret.py, document zuul-client encrypt 2020-12-09 11:30:59 +00:00
fake_bwrap.py Make most test cases work on MacOS 2020-02-20 12:59:38 +01:00
find-untrusted-exec.py Add a script to find untrusted execution tasks 2020-07-22 18:29:58 +00:00
github-debugging.py Fix Github debugging script 2022-03-08 12:13:31 +01:00
install-js-repos-rpm.sh Use node v10 instead of node v8 2019-02-04 21:26:37 +00:00
install-js-tools.sh Update nodejs runtime to version 16 2022-03-14 15:29:31 -07:00
mysqld.cnf Increase MySQL connection limit in tests 2021-11-24 13:30:28 -08:00
node_usage.py Small script to scrape Zuul job node usage 2018-10-30 09:17:57 -07:00
openapi_generate.py Add script to generate openapi spec 2024-03-09 11:25:40 -08:00
openssl.cnf Add TLS support for ZooKeeper 2020-03-18 14:47:37 -07:00
pip.sh Only run yarn build when necessary in tools/pip.sh 2022-10-07 13:29:25 -07:00
rebuild-docs.sh Add a script to rebuild old docs 2022-01-20 10:15:42 -08:00
test-logs.sh Cleanup actiongeneral usage 2022-05-04 14:20:16 -07:00
test-setup-docker.sh Add option to use in-container pg_dump in tests 2023-10-19 17:40:16 -07:00
test-setup.sh Bump up to python3.10 2022-07-01 15:59:48 -07:00
update-storyboard.py Re-enable E305 pep8 errors 2017-05-19 09:38:36 -04:00
yarn-build.sh Add noxfile and switch to nox 2022-12-20 08:57:53 -08:00
zk-analyze.py Add some ZK debug scripts 2022-01-26 12:59:39 -08:00
zk-ca.sh Use Absolute path in zk-ca.sh for openssl config 2020-05-28 11:48:01 +02:00
zk-dump.py Add some ZK debug scripts 2022-01-26 12:59:39 -08:00
zk-shell.py Add a zk-shell debug script 2022-01-27 08:25:35 -08:00
zoo.cfg Add ExistingDataWatch class 2021-07-02 15:22:29 -07:00
zuul-changes.py Don't fail on missing change_queues key in status json 2022-02-23 08:25:54 +01:00
zuul-clear-refs.py Zuul references cleaner 2015-07-20 18:57:04 +02:00