openapi: Add path descriptions

These are a little more detailed than the summaries.

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

diff --git a/docs/api/schemas/latest/patchwork.yaml b/docs/api/schemas/latest/patchwork.yaml
index 43da55c3f7fe7fa404bae833e56942b9d77d19f0..93e56fa0f4870d27f613cb37a8306ed61ff99349 100644 (file)
--- 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: []

diff --git a/docs/api/schemas/patchwork.j2 b/docs/api/schemas/patchwork.j2
index 541e4f8a8b865cb90d0b89fee4dcb3a4bc0cc783..516fbe88d8a24c1707bf38101a998a35c8adec52 100644 (file)
--- a/docs/api/schemas/patchwork.j2
+++ b/docs/api/schemas/patchwork.j2
@@ -23,6 +23,8 @@ paths:
 {% endif %}
     get:
       summary: List API resources.
+      description: |
+        Show paths to all supported API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -37,6 +39,9 @@ paths:
   /api/{{ version_url}}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'
@@ -81,6 +86,8 @@ paths:
 {% if version >= (1, 2) %}
     post:
       summary: Create a bundle.
+      description: |
+        Create a new bundle.
       operationId: bundles_create
       security:
         - basicAuth: []
@@ -120,6 +127,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':
@@ -139,6 +149,9 @@ paths:
 {% if version >= (1, 2) %}
     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: []
@@ -214,6 +227,8 @@ paths:
   /api/{{ version_url }}covers:
     get:
       summary: List cover letters.
+      description: |
+        List all cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -277,6 +292,8 @@ paths:
           type: integer
     get:
       summary: Show a cover letter.
+      description: |
+        Retrieve a cover letter by its ID.
       operationId: covers_read
       responses:
         '200':
@@ -305,6 +322,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'
@@ -350,6 +369,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':
@@ -368,6 +389,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'
@@ -402,6 +426,9 @@ paths:
   /api/{{ version_url }}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'
@@ -502,6 +529,8 @@ paths:
   /api/{{ version_url }}patches:
     get:
       summary: List patches.
+      description: |
+        List all patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -593,6 +622,8 @@ paths:
           type: integer
     get:
       summary: Show a patch.
+      description: |
+        Retrieve a patch by its ID.
       operationId: patches_read
       responses:
         '200':
@@ -611,6 +642,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: []
@@ -705,7 +739,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'
@@ -751,6 +787,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':
@@ -769,6 +807,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'
@@ -811,6 +852,8 @@ paths:
           type: integer
     get:
       summary: List checks.
+      description: |
+        List all checks for the given patch.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -915,6 +958,8 @@ paths:
           type: integer
     get:
       summary: Show a check.
+      description: |
+        Retrieve a check by its ID.
       operationId: checks_read
       responses:
         '200':
@@ -934,6 +979,9 @@ paths:
   /api/{{ version_url }}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: []
@@ -974,6 +1022,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: []
@@ -1002,6 +1053,8 @@ paths:
   /api/{{ version_url }}projects:
     get:
       summary: List projects.
+      description: |
+        List all projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1034,6 +1087,8 @@ paths:
           type: string
     get:
       summary: Show a project.
+      description: |
+        Retrieve a project by its ID.
       operationId: projects_read
       responses:
         '200':
@@ -1052,6 +1107,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: []
@@ -1123,6 +1181,9 @@ paths:
   /api/{{ version_url }}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'
@@ -1168,6 +1229,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':
@@ -1187,6 +1251,8 @@ paths:
   /api/{{ version_url }}users:
     get:
       summary: List users.
+      description: |
+        List all users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1227,6 +1293,8 @@ paths:
           type: integer
     get:
       summary: Show a user.
+      description: |
+        Retrieve a user by their ID.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1258,6 +1326,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: []

diff --git a/docs/api/schemas/v1.0/patchwork.yaml b/docs/api/schemas/v1.0/patchwork.yaml
index 8c58597570ba82b52a985526a3fce521a87fa4d5..d317f53fb3c599f2dc81dda9fed54f0b3c957ae1 100644 (file)
--- a/docs/api/schemas/v1.0/patchwork.yaml
+++ b/docs/api/schemas/v1.0/patchwork.yaml
@@ -18,6 +18,8 @@ paths:
   /api/1.0/:
     get:
       summary: List API resources.
+      description: |
+        Show paths to all supported API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -32,6 +34,9 @@ paths:
   /api/1.0/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'
@@ -84,6 +89,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':
@@ -103,6 +111,8 @@ paths:
   /api/1.0/covers:
     get:
       summary: List cover letters.
+      description: |
+        List all cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -156,6 +166,8 @@ paths:
           type: integer
     get:
       summary: Show a cover letter.
+      description: |
+        Retrieve a cover letter by its ID.
       operationId: covers_read
       responses:
         '200':
@@ -184,6 +196,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'
@@ -213,6 +227,9 @@ paths:
   /api/1.0/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'
@@ -306,6 +323,8 @@ paths:
   /api/1.0/patches:
     get:
       summary: List patches.
+      description: |
+        List all patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -380,6 +399,8 @@ paths:
           type: integer
     get:
       summary: Show a patch.
+      description: |
+        Retrieve a patch by its ID.
       operationId: patches_read
       responses:
         '200':
@@ -398,6 +419,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: []
@@ -476,7 +500,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'
@@ -514,6 +540,8 @@ paths:
           type: integer
     get:
       summary: List checks.
+      description: |
+        List all checks for the given patch.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -618,6 +646,8 @@ paths:
           type: integer
     get:
       summary: Show a check.
+      description: |
+        Retrieve a check by its ID.
       operationId: checks_read
       responses:
         '200':
@@ -637,6 +667,9 @@ paths:
   /api/1.0/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: []
@@ -677,6 +710,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: []
@@ -705,6 +741,8 @@ paths:
   /api/1.0/projects:
     get:
       summary: List projects.
+      description: |
+        List all projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -737,6 +775,8 @@ paths:
           type: string
     get:
       summary: Show a project.
+      description: |
+        Retrieve a project by its ID.
       operationId: projects_read
       responses:
         '200':
@@ -755,6 +795,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: []
@@ -826,6 +869,9 @@ paths:
   /api/1.0/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'
@@ -871,6 +917,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':
@@ -890,6 +939,8 @@ paths:
   /api/1.0/users:
     get:
       summary: List users.
+      description: |
+        List all users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -930,6 +981,8 @@ paths:
           type: integer
     get:
       summary: Show a user.
+      description: |
+        Retrieve a user by their ID.
       operationId: users_read
       security:
         - basicAuth: []
@@ -957,6 +1010,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: []

diff --git a/docs/api/schemas/v1.1/patchwork.yaml b/docs/api/schemas/v1.1/patchwork.yaml
index 44b7bf6ec66037ffd09ce810d609a135c53f5228..ce17d2f2dc537124ad01d12ff8d36813444cc6ab 100644 (file)
--- a/docs/api/schemas/v1.1/patchwork.yaml
+++ b/docs/api/schemas/v1.1/patchwork.yaml
@@ -18,6 +18,8 @@ paths:
   /api/1.1/:
     get:
       summary: List API resources.
+      description: |
+        Show paths to all supported API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -32,6 +34,9 @@ paths:
   /api/1.1/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'
@@ -84,6 +89,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':
@@ -103,6 +111,8 @@ paths:
   /api/1.1/covers:
     get:
       summary: List cover letters.
+      description: |
+        List all cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -156,6 +166,8 @@ paths:
           type: integer
     get:
       summary: Show a cover letter.
+      description: |
+        Retrieve a cover letter by its ID.
       operationId: covers_read
       responses:
         '200':
@@ -184,6 +196,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'
@@ -213,6 +227,9 @@ paths:
   /api/1.1/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'
@@ -306,6 +323,8 @@ paths:
   /api/1.1/patches:
     get:
       summary: List patches.
+      description: |
+        List all patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -380,6 +399,8 @@ paths:
           type: integer
     get:
       summary: Show a patch.
+      description: |
+        Retrieve a patch by its ID.
       operationId: patches_read
       responses:
         '200':
@@ -398,6 +419,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: []
@@ -476,7 +500,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'
@@ -514,6 +540,8 @@ paths:
           type: integer
     get:
       summary: List checks.
+      description: |
+        List all checks for the given patch.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -618,6 +646,8 @@ paths:
           type: integer
     get:
       summary: Show a check.
+      description: |
+        Retrieve a check by its ID.
       operationId: checks_read
       responses:
         '200':
@@ -637,6 +667,9 @@ paths:
   /api/1.1/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: []
@@ -677,6 +710,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: []
@@ -705,6 +741,8 @@ paths:
   /api/1.1/projects:
     get:
       summary: List projects.
+      description: |
+        List all projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -737,6 +775,8 @@ paths:
           type: string
     get:
       summary: Show a project.
+      description: |
+        Retrieve a project by its ID.
       operationId: projects_read
       responses:
         '200':
@@ -755,6 +795,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: []
@@ -826,6 +869,9 @@ paths:
   /api/1.1/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'
@@ -871,6 +917,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':
@@ -890,6 +939,8 @@ paths:
   /api/1.1/users:
     get:
       summary: List users.
+      description: |
+        List all users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -930,6 +981,8 @@ paths:
           type: integer
     get:
       summary: Show a user.
+      description: |
+        Retrieve a user by their ID.
       operationId: users_read
       security:
         - basicAuth: []
@@ -957,6 +1010,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: []

diff --git a/docs/api/schemas/v1.2/patchwork.yaml b/docs/api/schemas/v1.2/patchwork.yaml
index dcab86b4106c4e920b6567edfc3a8cb1604f2360..dddaafe53c41fa40f3c365b07fb4842bcfb01525 100644 (file)
--- a/docs/api/schemas/v1.2/patchwork.yaml
+++ b/docs/api/schemas/v1.2/patchwork.yaml
@@ -18,6 +18,8 @@ paths:
   /api/1.2/:
     get:
       summary: List API resources.
+      description: |
+        Show paths to all supported API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -32,6 +34,9 @@ paths:
   /api/1.2/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/1.2/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'
@@ -323,6 +342,9 @@ paths:
   /api/1.2/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'
@@ -417,6 +439,8 @@ paths:
   /api/1.2/patches:
     get:
       summary: List patches.
+      description: |
+        List all patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -506,6 +530,8 @@ paths:
           type: integer
     get:
       summary: Show a patch.
+      description: |
+        Retrieve a patch by its ID.
       operationId: patches_read
       responses:
         '200':
@@ -524,6 +550,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: []
@@ -614,7 +643,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'
@@ -652,6 +683,8 @@ paths:
           type: integer
     get:
       summary: List checks.
+      description: |
+        List all checks for the given patch.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -756,6 +789,8 @@ paths:
           type: integer
     get:
       summary: Show a check.
+      description: |
+        Retrieve a check by its ID.
       operationId: checks_read
       responses:
         '200':
@@ -775,6 +810,9 @@ paths:
   /api/1.2/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: []
@@ -815,6 +853,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: []
@@ -843,6 +884,8 @@ paths:
   /api/1.2/projects:
     get:
       summary: List projects.
+      description: |
+        List all projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -875,6 +918,8 @@ paths:
           type: string
     get:
       summary: Show a project.
+      description: |
+        Retrieve a project by its ID.
       operationId: projects_read
       responses:
         '200':
@@ -893,6 +938,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: []
@@ -964,6 +1012,9 @@ paths:
   /api/1.2/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'
@@ -1009,6 +1060,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':
@@ -1028,6 +1082,8 @@ paths:
   /api/1.2/users:
     get:
       summary: List users.
+      description: |
+        List all users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1068,6 +1124,8 @@ paths:
           type: integer
     get:
       summary: Show a user.
+      description: |
+        Retrieve a user by their ID.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1095,6 +1153,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: []

diff --git a/docs/api/schemas/v1.3/patchwork.yaml b/docs/api/schemas/v1.3/patchwork.yaml
index ea0f8ccac5c2a079d08b399f98ecb6f45f09f8a9..41b4483286819871429715c2749640f7b045ae4b 100644 (file)
--- a/docs/api/schemas/v1.3/patchwork.yaml
+++ b/docs/api/schemas/v1.3/patchwork.yaml
@@ -18,6 +18,8 @@ paths:
   /api/1.3/:
     get:
       summary: List API resources.
+      description: |
+        Show paths to all supported API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -32,6 +34,9 @@ paths:
   /api/1.3/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/1.3/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/1.3/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/1.3/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/1.3/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/1.3/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/1.3/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/1.3/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: []