[PATCH 00/17] Add OpenAPI 3.0.0 REST API spec

[Stephen Finucane]

Round 2. When we first added the REST API, attempts were made to
document this using OpenAPI 2.0 (f.k.a. Swagger). These floundered owing
to the tediousness of writing said spec from scratch. Thankfully, tools
have emerged [1][2] that allow us to generate specs from the code.  The
spec introduced here is based on the combined output of these tools,
with some additional tweaks to work around gaps in the generated output
(the embedded serializers in particular caused a lot of fuss).

The end result is something that we can use to validate the API,
validate clients and generate documentation from. To that effect, there
are a couple of patches at the beginning of the series that clean up
issues identified by running the tool. These should merge (and be
backported) regardless of the progress on the spec itself.

[1] https://www.django-rest-framework.org/api-guide/schemas/
[2] https://github.com/axnsan12/drf-yasg/

Stephen Finucane (17):
  REST: Add additional documentation
  REST: Show 'web_url' in embedded series responses
  REST: Ensure patch exists for check creation
  REST: Ensure submission exists for comment listing
  docs: Start documenting API using OpenAPI
  docs: Document the '/users' resource
  docs: Document the '/people' resource
  docs: Document the '/projects' resource
  docs: Document the '/bundles' resource
  docs: Document the '/covers' resource
  docs: Document the '/patches' resource
  docs: Document the '/series' resource
  docs: Document the '/covers/{coverID}/comments' resource
  docs: Document the '/patch/{patchID}/comments' resource
  docs: Document the '/patches/{patchID}/checks' resource
  docs: Document the '/events' resource
  docs: Make API document versioned

 .gitignore                                    |    1 +
 docs/api/schemas/generate_schema.py           |   29 +
 docs/api/schemas/patchwork.j2                 | 2207 +++++++++++++++++
 patchwork/api/check.py                        |   16 +-
 patchwork/api/comment.py                      |    5 +
 patchwork/api/embedded.py                     |    3 +-
 patchwork/api/index.py                        |    1 +
 patchwork/api/patch.py                        |   10 +-
 patchwork/api/project.py                      |   11 +-
 patchwork/api/user.py                         |   11 +-
 patchwork/tests/api/test_check.py             |   31 +-
 patchwork/tests/api/test_comment.py           |   13 +
 .../notes/issue-224-8f1c4207aa273ac6.yaml     |    5 +
 .../notes/issue-225-94215600c1b23f6e.yaml     |    6 +
 .../notes/issue-226-27ea72266d3ee9ac.yaml     |    7 +
 15 files changed, 2349 insertions(+), 7 deletions(-)
 create mode 100644 docs/api/schemas/generate_schema.py
 create mode 100644 docs/api/schemas/patchwork.j2
 create mode 100644 releasenotes/notes/issue-224-8f1c4207aa273ac6.yaml
 create mode 100644 releasenotes/notes/issue-225-94215600c1b23f6e.yaml
 create mode 100644 releasenotes/notes/issue-226-27ea72266d3ee9ac.yaml

-- 
2.17.2