docs: Make API document versioned

OpenAPI doesn't appear to support versioning natively, suggesting
instead that separate documents are kept. Rather than doing this
manually, let's use a templating tool - Jinja2, in this case - to
generate these document for us from a single master document.

Note that while we can now auto-generate these whenever we need them
(and we tend to avoid storing auto-generated assets in VCS), these
change so rarely that it's easier to just store them. This also means we
can reference the schemas themselves online. We do this in a following
change.

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/api/schemas/generate_schema.py b/docs/api/schemas/generate_schema.py
new file mode 100644 (file)
index 0000000..01ebaed
--- /dev/null
+++ b/docs/api/schemas/generate_schema.py
@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+
+import os
+
+import jinja2
+
+ROOT_DIR = os.path.dirname(os.path.realpath(__file__))
+VERSIONS = [(1, 0), (1, 1), None]
+LATEST_VERSION = (1, 1)
+
+
+def generate_schema():
+    env = jinja2.Environment(
+        loader=jinja2.FileSystemLoader(ROOT_DIR),
+        trim_blocks=True,
+        lstrip_blocks=True)
+    template = env.get_template('patchwork.j2')
+
+    for version in VERSIONS:
+        version_dir = os.path.join(
+            ROOT_DIR, 'v%d.%d' % version if version else 'latest')
+
+        if not os.path.exists(version_dir):
+            os.mkdir(version_dir)
+
+        version_str = '%d.%d' % (version or LATEST_VERSION)
+        version_url = '%d.%d/' % version if version else ''
+        version = version or LATEST_VERSION
+
+        with open(os.path.join(version_dir, 'patchwork.yaml'), 'wb') as fh:
+            template.stream(version=version, version_str=version_str,
+                            version_url=version_url).dump(fh, encoding='utf-8')
+
+
+if __name__ == '__main__':
+    generate_schema()

diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.j2
similarity index 97%
rename from docs/api/schemas/patchwork.yaml
rename to docs/api/schemas/patchwork.j2
index 875c1206a7265cd5a7f77876ff29505fcf901a14..e411b8fc08f429277a167aa4a59a51383e386510 100644 (file)
--- a/docs/api/schemas/patchwork.yaml
+++ b/docs/api/schemas/patchwork.j2
@@ -1,3 +1,6 @@
+{# You can obviously ignore the below when editing this template #}
+# DO NOT EDIT THIS FILE. It is generated from a template. Changes should be
+# proposed against the template.
 openapi: '3.0.0'
 info:
   title: Patchwork API
@@ -9,9 +12,9 @@ info:
   license:
     name: GPL v2 License
     url: https://www.gnu.org/licenses/gpl-2.0.html
-  version: '1.1'
+  version: '{{ version_str }}'
 paths:
-  /api/:
+  /api/{{ version_url}}:
     get:
       description: List API resources.
       operationId: api_list
@@ -25,7 +28,7 @@ paths:
                 $ref: '#/components/schemas/Index'
       tags:
       - api
-  /api/bundles/:
+  /api/{{ version_url}}bundles/:
     get:
       description: List bundles.
       operationId: bundles_list
@@ -66,7 +69,7 @@ paths:
                   $ref: '#/components/schemas/Bundle'
       tags:
       - bundles
-  /api/bundles/{id}/:
+  /api/{{ version_url }}bundles/{id}/:
     get:
       description: Show a bundle.
       operationId: bundles_read
@@ -93,7 +96,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - bundles
-  /api/covers/:
+  /api/{{ version_url }}covers/:
     get:
       description: List cover letters.
       operationId: covers_list
@@ -136,7 +139,7 @@ paths:
                   $ref: '#/components/schemas/CoverLetterList'
       tags:
       - covers
-  /api/covers/{id}/:
+  /api/{{ version_url }}covers/{id}/:
     get:
       description: Show a cover letter.
       operationId: covers_read
@@ -163,7 +166,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - covers
-  /api/covers/{id}/comments/:
+  /api/{{ version_url }}covers/{id}/comments/:
     get:
       description: List comments
       operationId: cover_comments_list
@@ -199,7 +202,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - comments
-  /api/events/:
+  /api/{{ version_url }}events/:
     get:
       description: List events.
       operationId: events_list
@@ -282,7 +285,7 @@ paths:
                       series-completed: '#/components/schemas/EventSeriesCompleted'
       tags:
       - events
-  /api/patches/:
+  /api/{{ version_url }}patches/:
     get:
       description: List patches.
       operationId: patches_list
@@ -343,7 +346,7 @@ paths:
                   $ref: '#/components/schemas/PatchList'
       tags:
       - patches
-  /api/patches/{id}/:
+  /api/{{ version_url }}patches/{id}/:
     get:
       description: Show a patch.
       operationId: patches_read
@@ -456,7 +459,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - patches
-  /api/patches/{id}/comments/:
+  /api/{{ version_url }}patches/{id}/comments/:
     get:
       description: List comments
       operationId: patch_comments_list
@@ -492,7 +495,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - comments
-  /api/patches/{patch_id}/checks/:
+  /api/{{ version_url }}patches/{patch_id}/checks/:
     get:
       description: List checks.
       operationId: checks_list
@@ -591,7 +594,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - checks
-  /api/patches/{patch_id}/checks/{check_id}/:
+  /api/{{ version_url }}patches/{patch_id}/checks/{check_id}/:
     get:
       description: Show a check.
       operationId: checks_read
@@ -625,7 +628,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - checks
-  /api/people/:
+  /api/{{ version_url }}people/:
     get:
       description: List people.
       operationId: people_list
@@ -657,7 +660,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - people
-  /api/people/{id}/:
+  /api/{{ version_url }}people/{id}/:
     get:
       description: Show a person.
       operationId: people_read
@@ -693,7 +696,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - people
-  /api/projects/:
+  /api/{{ version_url }}projects/:
     get:
       description: List projects.
       operationId: projects_list
@@ -716,7 +719,7 @@ paths:
                   $ref: '#/components/schemas/Project'
       tags:
       - projects
-  /api/projects/{id}/:
+  /api/{{ version_url }}projects/{id}/:
     get:
       description: Show a project.
       operationId: projects_read
@@ -829,7 +832,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - projects
-  /api/series/:
+  /api/{{ version_url }}series/:
     get:
       description: List series.
       operationId: series_list
@@ -866,7 +869,7 @@ paths:
                   $ref: '#/components/schemas/Series'
       tags:
       - series
-  /api/series/{id}/:
+  /api/{{ version_url }}series/{id}/:
     get:
       description: Show a series.
       operationId: series_read
@@ -893,7 +896,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - series
-  /api/users/:
+  /api/{{ version_url }}users/:
     get:
       description: List users.
       operationId: users_list
@@ -925,7 +928,7 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - users
-  /api/users/{id}/:
+  /api/{{ version_url }}users/{id}/:
     get:
       description: Show a user.
       operationId: users_read
@@ -1209,11 +1212,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         project:
           $ref: '#/components/schemas/ProjectEmbedded'
         name:
@@ -1328,11 +1333,13 @@ components:
           title: ID
           type: integer
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         msgid:
           title: Message ID
           type: string
@@ -1376,11 +1383,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         project:
           $ref: '#/components/schemas/ProjectEmbedded'
         msgid:
@@ -1406,21 +1415,25 @@ components:
           readOnly: true
           allOf:
           - $ref: '#/components/schemas/PersonEmbedded'
+{% if version > (1, 0) %}
         mbox:
           title: Mbox
           type: string
           format: uri
           readOnly: true
+{% endif %}
         series:
           type: array
           items:
             $ref: '#/components/schemas/SeriesEmbedded'
           readOnly: true
+{% if version > (1, 0) %}
         comments:
           title: Comments
           type: string
           format: uri
           readOnly: true
+{% endif %}
     CoverLetterDetail:
       allOf:
       - $ref: '#/components/schemas/CoverLetterList'
@@ -1589,11 +1602,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         project:
           $ref: '#/components/schemas/ProjectEmbedded'
         msgid:
@@ -1658,11 +1673,13 @@ components:
           items:
             $ref: '#/components/schemas/SeriesEmbedded'
           readOnly: true
+{% if version > (1, 0) %}
         comments:
           title: Comments
           type: string
           format: uri
           readOnly: true
+{% endif %}
         check:
           title: Check
           type: string
@@ -1823,6 +1840,7 @@ components:
             $ref: '#/components/schemas/UserEmbedded'
           readOnly: true
           uniqueItems: true
+{% if version > (1, 0) %}
         subject_match:
           title: Subject match
           description: Regex to match the subject against if only part of emails
@@ -1833,6 +1851,7 @@ components:
           type: string
           readOnly: true
           maxLength: 64
+{% endif %}
     Series:
       type: object
       properties:
@@ -1845,11 +1864,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         project:
           $ref: '#/components/schemas/ProjectEmbedded'
         name:
@@ -1988,11 +2009,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         msgid:
           title: Message ID
           type: string
@@ -2025,11 +2048,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         msgid:
           title: Message ID
           type: string
@@ -2139,11 +2164,13 @@ components:
           type: string
           format: uri
           readOnly: true
+{% if version > (1, 0) %}
         web_url:
           title: Web URL
           type: string
           format: uri
           readOnly: true
+{% endif %}
         name:
           title: Name
           description: An optional name to associate with the series, e.g. "John's PCI

diff --git a/docs/requirements.txt b/docs/requirements.txt
index ce48fc9204f6879b514c6033a85bca7cd2f60b4b..f2f955b3330f502cbfd658925c4e5385cceb201f 100644 (file)
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
 sphinx>=1.5
 reno>=2.2
 sphinx_rtd_theme==0.4.2
+jinja2