docs: Move common path parameters to parent

Turns out you don't have to nest common elements under individual routes
[1]. Less duplication and more sensible docs = winning.

[1] https://swagger.io/specification/#pathItemObject

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

1 files changed, 96 insertions, 165 deletions

diff --git a/docs/api/schemas/v1.2/patchwork.yaml b/docs/api/schemas/v1.2/patchwork.yaml
index 3b441db..8166840 100644
--- a/docs/api/schemas/v1.2/patchwork.yaml
+++ b/docs/api/schemas/v1.2/patchwork.yaml
@@ -103,17 +103,17 @@ paths:
       tags:
         - bundles
   /api/1.2/bundles/{id}/:
+    parameters:
+      - in: path
+        name: id
+        required: true
+        description: A unique integer value identifying this bundle.
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a bundle.
       operationId: bundles_read
-      parameters:
-        - in: path
-          name: id
-          required: true
-          description: A unique integer value identifying this bundle.
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -135,14 +135,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this bundle.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Bundle'
       responses:
@@ -178,14 +170,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this bundle.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Bundle'
       responses:
@@ -269,17 +253,17 @@ paths:
       tags:
         - covers
   /api/1.2/covers/{id}/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying this cover letter.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a cover letter.
       operationId: covers_read
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this cover letter.
-          required: true
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -296,18 +280,19 @@ paths:
       tags:
         - covers
   /api/1.2/covers/{id}/comments/:
+    parameters:
+      - in: path
+        name: id
+        description: >
+          A unique integer value identifying the parent cover letter.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: List comments
       operationId: cover_comments_list
       parameters:
-        - in: path
-          name: id
-          description: >
-            A unique integer value identifying the parent cover letter.
-          required: true
-          schema:
-            title: ID
-            type: integer
         - $ref: '#/components/parameters/Page'
         - $ref: '#/components/parameters/PageSize'
         - $ref: '#/components/parameters/Order'
@@ -505,17 +490,17 @@ paths:
       tags:
         - patches
   /api/1.2/patches/{id}/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying this patch.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a patch.
       operationId: patches_read
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this patch.
-          required: true
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -537,14 +522,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this patch.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Patch'
       responses:
@@ -586,14 +563,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this patch.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Patch'
       responses:
@@ -630,17 +599,18 @@ paths:
       tags:
         - patches
   /api/1.2/patches/{id}/comments/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying the parent patch.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: List comments
       operationId: patch_comments_list
       parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying the parent patch.
-          required: true
-          schema:
-            title: ID
-            type: integer
         - $ref: '#/components/parameters/Page'
         - $ref: '#/components/parameters/PageSize'
         - $ref: '#/components/parameters/Order'
@@ -666,17 +636,18 @@ paths:
       tags:
         - comments
   /api/1.2/patches/{patch_id}/checks/:
+    parameters:
+      - in: path
+        name: patch_id
+        description: A unique integer value identifying the parent patch.
+        required: true
+        schema:
+          title: Patch ID
+          type: integer
     get:
       description: List checks.
       operationId: checks_list
       parameters:
-        - in: path
-          name: patch_id
-          description: A unique integer value identifying the parent patch.
-          required: true
-          schema:
-            title: Patch ID
-            type: integer
         - $ref: '#/components/parameters/Page'
         - $ref: '#/components/parameters/PageSize'
         - $ref: '#/components/parameters/Order'
@@ -732,14 +703,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: patch_id
-          description: A unique integer value identifying the parent patch.
-          required: true
-          schema:
-            title: Patch ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Check'
       responses:
@@ -770,24 +733,24 @@ paths:
       tags:
         - checks
   /api/1.2/patches/{patch_id}/checks/{check_id}/:
+    parameters:
+      - in: path
+        name: patch_id
+        description: A unique integer value identifying the parent patch.
+        required: true
+        schema:
+          title: Patch ID
+          type: integer
+      - in: path
+        name: check_id
+        description: A unique integer value identifying this check.
+        required: true
+        schema:
+          title: Check ID
+          type: integer
     get:
       description: Show a check.
       operationId: checks_read
-      parameters:
-        - in: path
-          name: patch_id
-          description: A unique integer value identifying the parent patch.
-          required: true
-          schema:
-            title: Patch ID
-            type: integer
-        - in: path
-          name: check_id
-          description: A unique integer value identifying this check.
-          required: true
-          schema:
-            title: Check ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -836,20 +799,20 @@ paths:
       tags:
         - people
   /api/1.2/people/{id}/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying this person.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this person.
-          required: true
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -895,17 +858,17 @@ paths:
       tags:
         - projects
   /api/1.2/projects/{id}/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying this project.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a project.
       operationId: projects_read
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this project.
-          required: true
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -927,14 +890,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this project.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Project'
       responses:
@@ -970,14 +925,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this project.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/Project'
       responses:
@@ -1045,17 +992,17 @@ paths:
       tags:
         - series
   /api/1.2/series/{id}/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying this series.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a series.
       operationId: series_read
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this series.
-          required: true
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -1104,20 +1051,20 @@ paths:
       tags:
         - users
   /api/1.2/users/{id}/:
+    parameters:
+      - in: path
+        name: id
+        description: A unique integer value identifying this user.
+        required: true
+        schema:
+          title: ID
+          type: integer
     get:
       description: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this user.
-          required: true
-          schema:
-            title: ID
-            type: integer
       responses:
         '200':
           description: ''
@@ -1145,14 +1092,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this user.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/User'
       responses:
@@ -1188,14 +1127,6 @@ paths:
       security:
         - basicAuth: []
         - apiKeyAuth: []
-      parameters:
-        - in: path
-          name: id
-          description: A unique integer value identifying this user.
-          required: true
-          schema:
-            title: ID
-            type: integer
       requestBody:
         $ref: '#/components/requestBodies/User'
       responses: