From 3fbe760c9e855fa1d731533d97b2eb3988d4a350 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Mon, 22 Jan 2024 20:03:49 +0000
Subject: [PATCH] openapi: Set summary for paths

This shows up in e.g. reDoc, while the description does not. We will add
more detailed descriptions later.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/api/schemas/latest/patchwork.yaml | 65 ++++++++++++++------------
 docs/api/schemas/patchwork.j2          | 65 ++++++++++++++------------
 docs/api/schemas/v1.0/patchwork.yaml   | 48 +++++++++----------
 docs/api/schemas/v1.1/patchwork.yaml   | 48 +++++++++----------
 docs/api/schemas/v1.2/patchwork.yaml   | 57 +++++++++++-----------
 docs/api/schemas/v1.3/patchwork.yaml   | 65 ++++++++++++++------------
 6 files changed, 180 insertions(+), 168 deletions(-)

diff --git a/docs/api/schemas/latest/patchwork.yaml b/docs/api/schemas/latest/patchwork.yaml
index 7bed5451..43da55c3 100644
--- a/docs/api/schemas/latest/patchwork.yaml
+++ b/docs/api/schemas/latest/patchwork.yaml
@@ -17,7 +17,7 @@ info:
 paths:
   /api:
     get:
-      description: List API resources.
+      summary: List API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -31,7 +31,7 @@ paths:
         - api
   /api/bundles:
     get:
-      description: List bundles.
+      summary: List bundles.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -74,7 +74,7 @@ paths:
       tags:
         - bundles
     post:
-      description: Create a bundle.
+      summary: Create a bundle.
       operationId: bundles_create
       security:
         - basicAuth: []
@@ -112,7 +112,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a bundle.
+      summary: Show a bundle.
       operationId: bundles_read
       responses:
         '200':
@@ -130,7 +130,7 @@ paths:
       tags:
         - bundles
     patch:
-      description: Update a bundle (partial).
+      summary: Update a bundle (partial).
       operationId: bundles_partial_update
       security:
         - basicAuth: []
@@ -165,7 +165,10 @@ paths:
       tags:
         - bundles
     put:
-      description: Update a bundle.
+      summary: Update a bundle.
+      description:
+        Update an existing bundle.
+        The bundle must be owned by the currently authenticated user.
       operationId: bundles_update
       security:
         - basicAuth: []
@@ -201,7 +204,7 @@ paths:
         - bundles
   /api/covers:
     get:
-      description: List cover letters.
+      summary: List cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -262,7 +265,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a cover letter.
+      summary: Show a cover letter.
       operationId: covers_read
       responses:
         '200':
@@ -290,7 +293,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List cover letter comments
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -334,7 +337,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      description: Show a cover comment.
+      summary: Show a cover letter comment.
       operationId: cover_comments_read
       responses:
         '200':
@@ -352,7 +355,7 @@ paths:
       tags:
         - comments
     patch:
-      description: Update a cover comment (partial).
+      summary: Update a cover letter comment (partial).
       operationId: cover_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -385,7 +388,7 @@ paths:
         - comments
   /api/events:
     get:
-      description: List events.
+      summary: List events.
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -481,7 +484,7 @@ paths:
         - events
   /api/patches:
     get:
-      description: List patches.
+      summary: List patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -570,7 +573,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a patch.
+      summary: Show a patch.
       operationId: patches_read
       responses:
         '200':
@@ -588,7 +591,7 @@ paths:
       tags:
         - patches
     patch:
-      description: Update a patch (partial).
+      summary: Update a patch (partial).
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -679,7 +682,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List comments
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -723,7 +726,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      description: Show a patch comment.
+      summary: Show a patch comment.
       operationId: patch_comments_read
       responses:
         '200':
@@ -741,7 +744,7 @@ paths:
       tags:
         - comments
     patch:
-      description: Update a patch comment (partial).
+      summary: Update a patch comment (partial).
       operationId: patch_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -782,7 +785,7 @@ paths:
           title: Patch ID
           type: integer
     get:
-      description: List checks.
+      summary: List checks.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -835,7 +838,7 @@ paths:
       tags:
         - checks
     post:
-      description: Create a check.
+      summary: Create a check.
       operationId: checks_create
       security:
         - basicAuth: []
@@ -886,7 +889,7 @@ paths:
           title: Check ID
           type: integer
     get:
-      description: Show a check.
+      summary: Show a check.
       operationId: checks_read
       responses:
         '200':
@@ -905,7 +908,7 @@ paths:
         - checks
   /api/people:
     get:
-      description: List people.
+      summary: List people.
       operationId: people_list
       security:
         - basicAuth: []
@@ -945,7 +948,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a person.
+      summary: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
@@ -973,7 +976,7 @@ paths:
         - people
   /api/projects:
     get:
-      description: List projects.
+      summary: List projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1005,7 +1008,7 @@ paths:
           # TODO: Add regex?
           type: string
     get:
-      description: Show a project.
+      summary: Show a project.
       operationId: projects_read
       responses:
         '200':
@@ -1023,7 +1026,7 @@ paths:
       tags:
         - projects
     patch:
-      description: Update a project (partial).
+      summary: Update a project (partial).
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -1094,7 +1097,7 @@ paths:
         - projects
   /api/series:
     get:
-      description: List series.
+      summary: List series.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1139,7 +1142,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a series.
+      summary: Show a series.
       operationId: series_read
       responses:
         '200':
@@ -1158,7 +1161,7 @@ paths:
         - series
   /api/users:
     get:
-      description: List users.
+      summary: List users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1198,7 +1201,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a user.
+      summary: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1225,7 +1228,7 @@ paths:
       tags:
         - users
     patch:
-      description: Update a user (partial).
+      summary: Update a user (partial).
       operationId: users_partial_update
       security:
         - basicAuth: []
diff --git a/docs/api/schemas/patchwork.j2 b/docs/api/schemas/patchwork.j2
index 8b56a90b..541e4f8a 100644
--- a/docs/api/schemas/patchwork.j2
+++ b/docs/api/schemas/patchwork.j2
@@ -22,7 +22,7 @@ paths:
   /api:
 {% endif %}
     get:
-      description: List API resources.
+      summary: List API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -36,7 +36,7 @@ paths:
         - api
   /api/{{ version_url}}bundles:
     get:
-      description: List bundles.
+      summary: List bundles.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -80,7 +80,7 @@ paths:
         - bundles
 {% if version >= (1, 2) %}
     post:
-      description: Create a bundle.
+      summary: Create a bundle.
       operationId: bundles_create
       security:
         - basicAuth: []
@@ -119,7 +119,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a bundle.
+      summary: Show a bundle.
       operationId: bundles_read
       responses:
         '200':
@@ -138,7 +138,7 @@ paths:
         - bundles
 {% if version >= (1, 2) %}
     patch:
-      description: Update a bundle (partial).
+      summary: Update a bundle (partial).
       operationId: bundles_partial_update
       security:
         - basicAuth: []
@@ -173,7 +173,10 @@ paths:
       tags:
         - bundles
     put:
-      description: Update a bundle.
+      summary: Update a bundle.
+      description:
+        Update an existing bundle.
+        The bundle must be owned by the currently authenticated user.
       operationId: bundles_update
       security:
         - basicAuth: []
@@ -210,7 +213,7 @@ paths:
 {% endif %}
   /api/{{ version_url }}covers:
     get:
-      description: List cover letters.
+      summary: List cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -273,7 +276,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a cover letter.
+      summary: Show a cover letter.
       operationId: covers_read
       responses:
         '200':
@@ -301,7 +304,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List cover letter comments
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -346,7 +349,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      description: Show a cover comment.
+      summary: Show a cover letter comment.
       operationId: cover_comments_read
       responses:
         '200':
@@ -364,7 +367,7 @@ paths:
       tags:
         - comments
     patch:
-      description: Update a cover comment (partial).
+      summary: Update a cover letter comment (partial).
       operationId: cover_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -398,7 +401,7 @@ paths:
 {% endif %}
   /api/{{ version_url }}events:
     get:
-      description: List events.
+      summary: List events.
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -498,7 +501,7 @@ paths:
         - events
   /api/{{ version_url }}patches:
     get:
-      description: List patches.
+      summary: List patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -589,7 +592,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a patch.
+      summary: Show a patch.
       operationId: patches_read
       responses:
         '200':
@@ -607,7 +610,7 @@ paths:
       tags:
         - patches
     patch:
-      description: Update a patch (partial).
+      summary: Update a patch (partial).
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -702,7 +705,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List comments
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -747,7 +750,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      description: Show a patch comment.
+      summary: Show a patch comment.
       operationId: patch_comments_read
       responses:
         '200':
@@ -765,7 +768,7 @@ paths:
       tags:
         - comments
     patch:
-      description: Update a patch comment (partial).
+      summary: Update a patch comment (partial).
       operationId: patch_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -807,7 +810,7 @@ paths:
           title: Patch ID
           type: integer
     get:
-      description: List checks.
+      summary: List checks.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -860,7 +863,7 @@ paths:
       tags:
         - checks
     post:
-      description: Create a check.
+      summary: Create a check.
       operationId: checks_create
       security:
         - basicAuth: []
@@ -911,7 +914,7 @@ paths:
           title: Check ID
           type: integer
     get:
-      description: Show a check.
+      summary: Show a check.
       operationId: checks_read
       responses:
         '200':
@@ -930,7 +933,7 @@ paths:
         - checks
   /api/{{ version_url }}people:
     get:
-      description: List people.
+      summary: List people.
       operationId: people_list
       security:
         - basicAuth: []
@@ -970,7 +973,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a person.
+      summary: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
@@ -998,7 +1001,7 @@ paths:
         - people
   /api/{{ version_url }}projects:
     get:
-      description: List projects.
+      summary: List projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1030,7 +1033,7 @@ paths:
           # TODO: Add regex?
           type: string
     get:
-      description: Show a project.
+      summary: Show a project.
       operationId: projects_read
       responses:
         '200':
@@ -1048,7 +1051,7 @@ paths:
       tags:
         - projects
     patch:
-      description: Update a project (partial).
+      summary: Update a project (partial).
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -1119,7 +1122,7 @@ paths:
         - projects
   /api/{{ version_url }}series:
     get:
-      description: List series.
+      summary: List series.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1164,7 +1167,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a series.
+      summary: Show a series.
       operationId: series_read
       responses:
         '200':
@@ -1183,7 +1186,7 @@ paths:
         - series
   /api/{{ version_url }}users:
     get:
-      description: List users.
+      summary: List users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1223,7 +1226,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a user.
+      summary: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1254,7 +1257,7 @@ paths:
       tags:
         - users
     patch:
-      description: Update a user (partial).
+      summary: Update a user (partial).
       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 1f92590b..8c585975 100644
--- a/docs/api/schemas/v1.0/patchwork.yaml
+++ b/docs/api/schemas/v1.0/patchwork.yaml
@@ -17,7 +17,7 @@ info:
 paths:
   /api/1.0/:
     get:
-      description: List API resources.
+      summary: List API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -31,7 +31,7 @@ paths:
         - api
   /api/1.0/bundles:
     get:
-      description: List bundles.
+      summary: List bundles.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -83,7 +83,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a bundle.
+      summary: Show a bundle.
       operationId: bundles_read
       responses:
         '200':
@@ -102,7 +102,7 @@ paths:
         - bundles
   /api/1.0/covers:
     get:
-      description: List cover letters.
+      summary: List cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -155,7 +155,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a cover letter.
+      summary: Show a cover letter.
       operationId: covers_read
       responses:
         '200':
@@ -183,7 +183,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List cover letter comments
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -212,7 +212,7 @@ paths:
         - comments
   /api/1.0/events:
     get:
-      description: List events.
+      summary: List events.
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -305,7 +305,7 @@ paths:
         - events
   /api/1.0/patches:
     get:
-      description: List patches.
+      summary: List patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -379,7 +379,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a patch.
+      summary: Show a patch.
       operationId: patches_read
       responses:
         '200':
@@ -397,7 +397,7 @@ paths:
       tags:
         - patches
     patch:
-      description: Update a patch (partial).
+      summary: Update a patch (partial).
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -476,7 +476,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List comments
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -513,7 +513,7 @@ paths:
           title: Patch ID
           type: integer
     get:
-      description: List checks.
+      summary: List checks.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -566,7 +566,7 @@ paths:
       tags:
         - checks
     post:
-      description: Create a check.
+      summary: Create a check.
       operationId: checks_create
       security:
         - basicAuth: []
@@ -617,7 +617,7 @@ paths:
           title: Check ID
           type: integer
     get:
-      description: Show a check.
+      summary: Show a check.
       operationId: checks_read
       responses:
         '200':
@@ -636,7 +636,7 @@ paths:
         - checks
   /api/1.0/people:
     get:
-      description: List people.
+      summary: List people.
       operationId: people_list
       security:
         - basicAuth: []
@@ -676,7 +676,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a person.
+      summary: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
@@ -704,7 +704,7 @@ paths:
         - people
   /api/1.0/projects:
     get:
-      description: List projects.
+      summary: List projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -736,7 +736,7 @@ paths:
           # TODO: Add regex?
           type: string
     get:
-      description: Show a project.
+      summary: Show a project.
       operationId: projects_read
       responses:
         '200':
@@ -754,7 +754,7 @@ paths:
       tags:
         - projects
     patch:
-      description: Update a project (partial).
+      summary: Update a project (partial).
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -825,7 +825,7 @@ paths:
         - projects
   /api/1.0/series:
     get:
-      description: List series.
+      summary: List series.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -870,7 +870,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a series.
+      summary: Show a series.
       operationId: series_read
       responses:
         '200':
@@ -889,7 +889,7 @@ paths:
         - series
   /api/1.0/users:
     get:
-      description: List users.
+      summary: List users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -929,7 +929,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a user.
+      summary: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
@@ -956,7 +956,7 @@ paths:
       tags:
         - users
     patch:
-      description: Update a user (partial).
+      summary: Update a user (partial).
       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 14b6de28..44b7bf6e 100644
--- a/docs/api/schemas/v1.1/patchwork.yaml
+++ b/docs/api/schemas/v1.1/patchwork.yaml
@@ -17,7 +17,7 @@ info:
 paths:
   /api/1.1/:
     get:
-      description: List API resources.
+      summary: List API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -31,7 +31,7 @@ paths:
         - api
   /api/1.1/bundles:
     get:
-      description: List bundles.
+      summary: List bundles.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -83,7 +83,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a bundle.
+      summary: Show a bundle.
       operationId: bundles_read
       responses:
         '200':
@@ -102,7 +102,7 @@ paths:
         - bundles
   /api/1.1/covers:
     get:
-      description: List cover letters.
+      summary: List cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -155,7 +155,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a cover letter.
+      summary: Show a cover letter.
       operationId: covers_read
       responses:
         '200':
@@ -183,7 +183,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List cover letter comments
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -212,7 +212,7 @@ paths:
         - comments
   /api/1.1/events:
     get:
-      description: List events.
+      summary: List events.
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -305,7 +305,7 @@ paths:
         - events
   /api/1.1/patches:
     get:
-      description: List patches.
+      summary: List patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -379,7 +379,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a patch.
+      summary: Show a patch.
       operationId: patches_read
       responses:
         '200':
@@ -397,7 +397,7 @@ paths:
       tags:
         - patches
     patch:
-      description: Update a patch (partial).
+      summary: Update a patch (partial).
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -476,7 +476,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List comments
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -513,7 +513,7 @@ paths:
           title: Patch ID
           type: integer
     get:
-      description: List checks.
+      summary: List checks.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -566,7 +566,7 @@ paths:
       tags:
         - checks
     post:
-      description: Create a check.
+      summary: Create a check.
       operationId: checks_create
       security:
         - basicAuth: []
@@ -617,7 +617,7 @@ paths:
           title: Check ID
           type: integer
     get:
-      description: Show a check.
+      summary: Show a check.
       operationId: checks_read
       responses:
         '200':
@@ -636,7 +636,7 @@ paths:
         - checks
   /api/1.1/people:
     get:
-      description: List people.
+      summary: List people.
       operationId: people_list
       security:
         - basicAuth: []
@@ -676,7 +676,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a person.
+      summary: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
@@ -704,7 +704,7 @@ paths:
         - people
   /api/1.1/projects:
     get:
-      description: List projects.
+      summary: List projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -736,7 +736,7 @@ paths:
           # TODO: Add regex?
           type: string
     get:
-      description: Show a project.
+      summary: Show a project.
       operationId: projects_read
       responses:
         '200':
@@ -754,7 +754,7 @@ paths:
       tags:
         - projects
     patch:
-      description: Update a project (partial).
+      summary: Update a project (partial).
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -825,7 +825,7 @@ paths:
         - projects
   /api/1.1/series:
     get:
-      description: List series.
+      summary: List series.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -870,7 +870,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a series.
+      summary: Show a series.
       operationId: series_read
       responses:
         '200':
@@ -889,7 +889,7 @@ paths:
         - series
   /api/1.1/users:
     get:
-      description: List users.
+      summary: List users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -929,7 +929,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a user.
+      summary: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
@@ -956,7 +956,7 @@ paths:
       tags:
         - users
     patch:
-      description: Update a user (partial).
+      summary: Update a user (partial).
       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 7135a20f..dcab86b4 100644
--- a/docs/api/schemas/v1.2/patchwork.yaml
+++ b/docs/api/schemas/v1.2/patchwork.yaml
@@ -17,7 +17,7 @@ info:
 paths:
   /api/1.2/:
     get:
-      description: List API resources.
+      summary: List API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -31,7 +31,7 @@ paths:
         - api
   /api/1.2/bundles:
     get:
-      description: List bundles.
+      summary: List bundles.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -74,7 +74,7 @@ paths:
       tags:
         - bundles
     post:
-      description: Create a bundle.
+      summary: Create a bundle.
       operationId: bundles_create
       security:
         - basicAuth: []
@@ -112,7 +112,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a bundle.
+      summary: Show a bundle.
       operationId: bundles_read
       responses:
         '200':
@@ -130,7 +130,7 @@ paths:
       tags:
         - bundles
     patch:
-      description: Update a bundle (partial).
+      summary: Update a bundle (partial).
       operationId: bundles_partial_update
       security:
         - basicAuth: []
@@ -165,7 +165,10 @@ paths:
       tags:
         - bundles
     put:
-      description: Update a bundle.
+      summary: Update a bundle.
+      description:
+        Update an existing bundle.
+        The bundle must be owned by the currently authenticated user.
       operationId: bundles_update
       security:
         - basicAuth: []
@@ -201,7 +204,7 @@ paths:
         - bundles
   /api/1.2/covers:
     get:
-      description: List cover letters.
+      summary: List cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -262,7 +265,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a cover letter.
+      summary: Show a cover letter.
       operationId: covers_read
       responses:
         '200':
@@ -290,7 +293,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List cover letter comments
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -319,7 +322,7 @@ paths:
         - comments
   /api/1.2/events:
     get:
-      description: List events.
+      summary: List events.
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -413,7 +416,7 @@ paths:
         - events
   /api/1.2/patches:
     get:
-      description: List patches.
+      summary: List patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -502,7 +505,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a patch.
+      summary: Show a patch.
       operationId: patches_read
       responses:
         '200':
@@ -520,7 +523,7 @@ paths:
       tags:
         - patches
     patch:
-      description: Update a patch (partial).
+      summary: Update a patch (partial).
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -611,7 +614,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List comments
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -648,7 +651,7 @@ paths:
           title: Patch ID
           type: integer
     get:
-      description: List checks.
+      summary: List checks.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -701,7 +704,7 @@ paths:
       tags:
         - checks
     post:
-      description: Create a check.
+      summary: Create a check.
       operationId: checks_create
       security:
         - basicAuth: []
@@ -752,7 +755,7 @@ paths:
           title: Check ID
           type: integer
     get:
-      description: Show a check.
+      summary: Show a check.
       operationId: checks_read
       responses:
         '200':
@@ -771,7 +774,7 @@ paths:
         - checks
   /api/1.2/people:
     get:
-      description: List people.
+      summary: List people.
       operationId: people_list
       security:
         - basicAuth: []
@@ -811,7 +814,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a person.
+      summary: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
@@ -839,7 +842,7 @@ paths:
         - people
   /api/1.2/projects:
     get:
-      description: List projects.
+      summary: List projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -871,7 +874,7 @@ paths:
           # TODO: Add regex?
           type: string
     get:
-      description: Show a project.
+      summary: Show a project.
       operationId: projects_read
       responses:
         '200':
@@ -889,7 +892,7 @@ paths:
       tags:
         - projects
     patch:
-      description: Update a project (partial).
+      summary: Update a project (partial).
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -960,7 +963,7 @@ paths:
         - projects
   /api/1.2/series:
     get:
-      description: List series.
+      summary: List series.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1005,7 +1008,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a series.
+      summary: Show a series.
       operationId: series_read
       responses:
         '200':
@@ -1024,7 +1027,7 @@ paths:
         - series
   /api/1.2/users:
     get:
-      description: List users.
+      summary: List users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1064,7 +1067,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a user.
+      summary: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1091,7 +1094,7 @@ paths:
       tags:
         - users
     patch:
-      description: Update a user (partial).
+      summary: Update a user (partial).
       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 7ad6129b..ea0f8cca 100644
--- a/docs/api/schemas/v1.3/patchwork.yaml
+++ b/docs/api/schemas/v1.3/patchwork.yaml
@@ -17,7 +17,7 @@ info:
 paths:
   /api/1.3/:
     get:
-      description: List API resources.
+      summary: List API resources.
       operationId: api_list
       parameters: []
       responses:
@@ -31,7 +31,7 @@ paths:
         - api
   /api/1.3/bundles:
     get:
-      description: List bundles.
+      summary: List bundles.
       operationId: bundles_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -74,7 +74,7 @@ paths:
       tags:
         - bundles
     post:
-      description: Create a bundle.
+      summary: Create a bundle.
       operationId: bundles_create
       security:
         - basicAuth: []
@@ -112,7 +112,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a bundle.
+      summary: Show a bundle.
       operationId: bundles_read
       responses:
         '200':
@@ -130,7 +130,7 @@ paths:
       tags:
         - bundles
     patch:
-      description: Update a bundle (partial).
+      summary: Update a bundle (partial).
       operationId: bundles_partial_update
       security:
         - basicAuth: []
@@ -165,7 +165,10 @@ paths:
       tags:
         - bundles
     put:
-      description: Update a bundle.
+      summary: Update a bundle.
+      description:
+        Update an existing bundle.
+        The bundle must be owned by the currently authenticated user.
       operationId: bundles_update
       security:
         - basicAuth: []
@@ -201,7 +204,7 @@ paths:
         - bundles
   /api/1.3/covers:
     get:
-      description: List cover letters.
+      summary: List cover letters.
       operationId: covers_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -262,7 +265,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a cover letter.
+      summary: Show a cover letter.
       operationId: covers_read
       responses:
         '200':
@@ -290,7 +293,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List cover letter comments
       operationId: cover_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -334,7 +337,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      description: Show a cover comment.
+      summary: Show a cover letter comment.
       operationId: cover_comments_read
       responses:
         '200':
@@ -352,7 +355,7 @@ paths:
       tags:
         - comments
     patch:
-      description: Update a cover comment (partial).
+      summary: Update a cover letter comment (partial).
       operationId: cover_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -385,7 +388,7 @@ paths:
         - comments
   /api/1.3/events:
     get:
-      description: List events.
+      summary: List events.
       operationId: events_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -481,7 +484,7 @@ paths:
         - events
   /api/1.3/patches:
     get:
-      description: List patches.
+      summary: List patches.
       operationId: patches_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -570,7 +573,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a patch.
+      summary: Show a patch.
       operationId: patches_read
       responses:
         '200':
@@ -588,7 +591,7 @@ paths:
       tags:
         - patches
     patch:
-      description: Update a patch (partial).
+      summary: Update a patch (partial).
       operationId: patches_partial_update
       security:
         - basicAuth: []
@@ -679,7 +682,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: List comments
+      summary: List comments
       operationId: patch_comments_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -723,7 +726,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      description: Show a patch comment.
+      summary: Show a patch comment.
       operationId: patch_comments_read
       responses:
         '200':
@@ -741,7 +744,7 @@ paths:
       tags:
         - comments
     patch:
-      description: Update a patch comment (partial).
+      summary: Update a patch comment (partial).
       operationId: patch_comments_partial_update
       requestBody:
         $ref: '#/components/requestBodies/Comment'
@@ -782,7 +785,7 @@ paths:
           title: Patch ID
           type: integer
     get:
-      description: List checks.
+      summary: List checks.
       operationId: checks_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -835,7 +838,7 @@ paths:
       tags:
         - checks
     post:
-      description: Create a check.
+      summary: Create a check.
       operationId: checks_create
       security:
         - basicAuth: []
@@ -886,7 +889,7 @@ paths:
           title: Check ID
           type: integer
     get:
-      description: Show a check.
+      summary: Show a check.
       operationId: checks_read
       responses:
         '200':
@@ -905,7 +908,7 @@ paths:
         - checks
   /api/1.3/people:
     get:
-      description: List people.
+      summary: List people.
       operationId: people_list
       security:
         - basicAuth: []
@@ -945,7 +948,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a person.
+      summary: Show a person.
       operationId: people_read
       security:
         - basicAuth: []
@@ -973,7 +976,7 @@ paths:
         - people
   /api/1.3/projects:
     get:
-      description: List projects.
+      summary: List projects.
       operationId: projects_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1005,7 +1008,7 @@ paths:
           # TODO: Add regex?
           type: string
     get:
-      description: Show a project.
+      summary: Show a project.
       operationId: projects_read
       responses:
         '200':
@@ -1023,7 +1026,7 @@ paths:
       tags:
         - projects
     patch:
-      description: Update a project (partial).
+      summary: Update a project (partial).
       operationId: projects_partial_update
       security:
         - basicAuth: []
@@ -1094,7 +1097,7 @@ paths:
         - projects
   /api/1.3/series:
     get:
-      description: List series.
+      summary: List series.
       operationId: series_list
       parameters:
         - $ref: '#/components/parameters/Page'
@@ -1139,7 +1142,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a series.
+      summary: Show a series.
       operationId: series_read
       responses:
         '200':
@@ -1158,7 +1161,7 @@ paths:
         - series
   /api/1.3/users:
     get:
-      description: List users.
+      summary: List users.
       operationId: users_list
       security:
         - basicAuth: []
@@ -1198,7 +1201,7 @@ paths:
           title: ID
           type: integer
     get:
-      description: Show a user.
+      summary: Show a user.
       operationId: users_read
       security:
         - basicAuth: []
@@ -1225,7 +1228,7 @@ paths:
       tags:
         - users
     patch:
-      description: Update a user (partial).
+      summary: Update a user (partial).
       operationId: users_partial_update
       security:
         - basicAuth: []
-- 
2.47.3