docs: Document endpoint to link two series

Closes getpatchwork#506

Signed-off-by: andrepapoti <[email protected]>

Author: andrepapoti

docs/api/schemas/generate-schemas.py

@@ -14,8 +14,8 @@
     yaml = None
 
 ROOT_DIR = os.path.dirname(os.path.realpath(__file__))
-VERSIONS = [(1, 0), (1, 1), (1, 2), (1, 3), None]
-LATEST_VERSION = (1, 3)
+VERSIONS = [(1, 0), (1, 1), (1, 2), (1, 3), (1, 4), None]
+LATEST_VERSION = (1, 4)
 
 
 def generate_schemas():

docs/api/schemas/latest/patchwork.yaml

@@ -13,7 +13,7 @@ info:
   license:
     name: GPL v2 License
     url: https://www.gnu.org/licenses/gpl-2.0.html
-  version: '1.3'
+  version: '1.4'
 paths:
   /api:
     get:
@@ -1223,6 +1223,42 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
         - series
+    patch:
+      summary: Link series to set a relationship between them
+      description: |
+        Apply a partial update to a Series, where only a few fields of the model are allowed:
+        - previous_series: Set the provided series as coming before the one specified by the id;
+        - subsequent_series: Set the provided series as coming after the one specified by the id;
+        - required_series: Set the provided series as requirements for one specified by the id;
+        - required_by_series: Set the series specified by the id as a requirement for the provided ones.
+      operationId: series_link
+      responses:
+        '200':
+          description: 'Updated series'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Series'
+        '400':
+          description: 'Bad request'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: 'Forbidden'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: 'Not found'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      tags:
+        - series
   /api/users:
     get:
       summary: List users.
@@ -2605,6 +2641,34 @@ components:
             $ref: '#/components/schemas/PatchEmbedded'
           readOnly: true
           uniqueItems: true
+        previous_series:
+          title: Previous series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+        subsequent_series:
+          title: Subsequent series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+        required_series:
+          title: Required series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+        required_by_series:
+          title: Required by series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
     User:
       type: object
       title: User

docs/api/schemas/patchwork.j2

@@ -1248,6 +1248,44 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
         - series
+{% if version >= (1, 4) %}
+    patch:
+      summary: Link series to set a relationship between them
+      description: |
+        Apply a partial update to a Series, where only a few fields of the model are allowed:
+        - previous_series: Set the provided series as coming before the one specified by the id;
+        - subsequent_series: Set the provided series as coming after the one specified by the id;
+        - required_series: Set the provided series as requirements for one specified by the id;
+        - required_by_series: Set the series specified by the id as a requirement for the provided ones.
+      operationId: series_link
+      responses:
+        '200':
+          description: 'Updated series'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Series'
+        '400':
+          description: 'Bad request'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: 'Forbidden'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: 'Not found'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      tags:
+        - series
+{% endif %}
   /api/{{ version_url }}users:
     get:
       summary: List users.
@@ -2699,6 +2737,36 @@ components:
             $ref: '#/components/schemas/PatchEmbedded'
           readOnly: true
           uniqueItems: true
+{% if version >= (1, 4) %}
+        previous_series:
+          title: Previous series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+        subsequent_series:
+          title: Subsequent series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+        required_series:
+          title: Required series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+        required_by_series:
+          title: Required by series
+          type: array
+          items:
+            $ref: '#/components/schemas/Series'
+          readOnly: true
+          uniqueItems: true
+{% endif %}
     User:
       type: object
       title: User