openapi: Add path descriptions

These are a little more detailed than the summaries. Signed-off-by: Stephen Finucane <[email protected]>
andrepapoti · Jan 22, 2024 · 7494873 · 7494873
1 parent 3fbe760
commit 7494873
Show file tree

Hide file tree

Showing 6 changed files with 392 additions and 6 deletions.
diff --git a/docs/api/schemas/latest/patchwork.yaml b/docs/api/schemas/latest/patchwork.yaml
@@ -18,6 +18,8 @@ paths:
   /api:
     get:
       summary: List API resources.
+      description: |
+        Show paths to all supported API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -32,6 +34,9 @@ paths:
   /api/bundles:
     get:
       summary: List bundles.
+      description: |
+        List all bundles that the current user has access to.
+        For unauthenticated requests, only public bundles can be shown.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -75,6 +80,8 @@ paths:
         - bundles
     post:
       summary: Create a bundle.
+      description: |
+        Create a new bundle.
       operationId: bundles_create
       security:
         - basicAuth: []
@@ -113,6 +120,9 @@ paths:
           type: integer
     get:
       summary: Show a bundle.
+      description: |
+        Retrieve a bundle by its ID.
+        The bundle must be either be public or be owned by the currently authenticated user.
       operationId: bundles_read
       responses:
         '200':
@@ -131,6 +141,9 @@ paths:
         - bundles
     patch:
       summary: Update a bundle (partial).
+      description:
+        Partially update an existing bundle.
+        The bundle must be owned by the currently authenticated user.
       operationId: bundles_partial_update
       security:
         - basicAuth: []
@@ -205,6 +218,8 @@ paths:
   /api/covers:
     get:
       summary: List cover letters.
+      description: |
+        List all cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -266,6 +281,8 @@ paths:
           type: integer
     get:
       summary: Show a cover letter.
+      description: |
+        Retrieve a cover letter by its ID.
       operationId: covers_read
       responses:
         '200':
@@ -294,6 +311,8 @@ paths:
           type: integer
     get:
       summary: List cover letter comments
+      description: |
+        List all comments for the given cover letter.
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -338,6 +357,8 @@ paths:
           type: integer
     get:
       summary: Show a cover letter comment.
+      description: |
+        Retrieve a cover letter comment by its ID.
       operationId: cover_comments_read
       responses:
         '200':
@@ -356,6 +377,9 @@ paths:
         - comments
     patch:
       summary: Update a cover letter comment (partial).
+      description:
+        Partially update an existing cover letter comment.
+        You must be a maintainer of the project that the cover letter comment belongs to.
       operationId: cover_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -389,6 +413,9 @@ paths:
   /api/events:
     get:
       summary: List events.
+      description: |
+        List all events.
+        This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s).
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -485,6 +512,8 @@ paths:
   /api/patches:
     get:
       summary: List patches.
+      description: |
+        List all patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -574,6 +603,8 @@ paths:
           type: integer
     get:
       summary: Show a patch.
+      description: |
+        Retrieve a patch by its ID.
       operationId: patches_read
       responses:
         '200':
@@ -592,6 +623,9 @@ paths:
         - patches
     patch:
       summary: Update a patch (partial).
+      description:
+        Partially update an existing patch.
+        You must be a maintainer of the project that the patch belongs to.
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -682,7 +716,9 @@ paths:
           title: ID
           type: integer
     get:
-      summary: List comments
+      summary: List patch comments
+      description: |
+        List all comments for the given patch.
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -727,6 +763,8 @@ paths:
           type: integer
     get:
       summary: Show a patch comment.
+      description: |
+        Retrieve a patch comment by its ID and the ID of the patch.
       operationId: patch_comments_read
       responses:
         '200':
@@ -745,6 +783,9 @@ paths:
         - comments
     patch:
       summary: Update a patch comment (partial).
+      description:
+        Partially update an existing patch comment.
+        You must be a maintainer of the project that the patch comment belongs to.
       operationId: patch_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -786,6 +827,8 @@ paths:
           type: integer
     get:
       summary: List checks.
+      description: |
+        List all checks for the given patch.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -890,6 +933,8 @@ paths:
           type: integer
     get:
       summary: Show a check.
+      description: |
+        Retrieve a check by its ID.
       operationId: checks_read
       responses:
         '200':
@@ -909,6 +954,9 @@ paths:
   /api/people:
     get:
       summary: List people.
+      description: |
+        List all people.
+        A person is anyone that has submitted a patch, a series of patches, or a comment to any project.
       operationId: people_list
       security:
         - basicAuth: []
@@ -949,6 +997,9 @@ paths:
           type: integer
     get:
       summary: Show a person.
+      description: |
+        Retrieve a person by their ID.
+        A person is anyone that has submitted a patch, a series of patches, or a comment to any project.
       operationId: people_read
       security:
         - basicAuth: []
@@ -977,6 +1028,8 @@ paths:
   /api/projects:
     get:
       summary: List projects.
+      description: |
+        List all projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1009,6 +1062,8 @@ paths:
           type: string
     get:
       summary: Show a project.
+      description: |
+        Retrieve a project by its ID.
       operationId: projects_read
       responses:
         '200':
@@ -1027,6 +1082,9 @@ paths:
         - projects
     patch:
       summary: Update a project (partial).
+      description:
+        Partially update an existing project.
+        You must be a maintainer of the project.
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -1098,6 +1156,9 @@ paths:
   /api/series:
     get:
       summary: List series.
+      description: |
+        List all series.
+        A series is a collection of patches with an optional cover letter.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1143,6 +1204,9 @@ paths:
           type: integer
     get:
       summary: Show a series.
+      description: |
+        Retrieve a series by its ID.
+        A series is a collection of patches with an optional cover letter.
       operationId: series_read
       responses:
         '200':
@@ -1162,6 +1226,8 @@ paths:
   /api/users:
     get:
       summary: List users.
+      description: |
+        List all users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1202,6 +1268,8 @@ paths:
           type: integer
     get:
       summary: Show a user.
+      description: |
+        Retrieve a user by their ID.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1229,6 +1297,9 @@ paths:
         - users
     patch:
       summary: Update a user (partial).
+      description:
+        Partially update a user account.
+        Only super users are allowed to update other user's accounts.
       operationId: users_partial_update
       security:
         - basicAuth: []