docs: update comments endpoint schemas

- Add create maintainer note requests
- Update Comment to allow empty msgid

Signed-off-by: Victor Accarini <[email protected]>

Author: victor-accarini

docs/api/schemas/latest/patchwork.yaml

@@ -319,6 +319,18 @@ paths:
         - $ref: '#/components/parameters/PageSize'
         - $ref: '#/components/parameters/Order'
         - $ref: '#/components/parameters/Search'
+        - in: query
+          name: type
+          description: |
+            Filter comment type. Use 'notes' to show only maintainer notes,
+            'comments' to show only regular comments, or omit for default behavior
+            (which only shows regular comments).
+          schema:
+            title: ''
+            type: string
+            enum:
+              - notes
+              - comments
       responses:
         '200':
           description: 'List of comments'
@@ -339,6 +351,43 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
         - comments
+    post:
+      summary: Create a maintainer note in the cover
+      description: |
+        Create a maintainer note in the cover
+      operationId: cover_maintainer_note_create
+      requestBody:
+        $ref: '#/components/requestBodies/MaintainerNote'
+      responses:
+        '201':
+          description: 'Created maintainer note'
+          headers:
+            Link:
+              $ref: '#/components/headers/Link'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Comment'
+        '400':
+          description: 'Invalid request'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMaintainerNote'
+        '403':
+          description: 'Forbidden'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: 'Not found'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      tags:
+        - comments
   /api/covers/{cover_id}/comments/{comment_id}:
     parameters:
       - in: path
@@ -356,7 +405,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      summary: Show a cover letter comment.
+      summary: Show a cover letter comment or maintainer note.
       description: |
         Retrieve a cover letter comment by its ID.
       operationId: cover_comments_read
@@ -376,7 +425,7 @@ paths:
       tags:
         - comments
     patch:
-      summary: Update a cover letter comment (partial).
+      summary: Update a cover letter comment or maintainer note (partial).
       description:
         Partially update an existing cover letter comment.
         You must be a maintainer of the project that the cover letter comment belongs to.
@@ -725,6 +774,18 @@ paths:
         - $ref: '#/components/parameters/PageSize'
         - $ref: '#/components/parameters/Order'
         - $ref: '#/components/parameters/Search'
+        - in: query
+          name: type
+          description: |
+            Filter comment type. Use 'notes' to show only maintainer notes,
+            'comments' to show only regular comments, or omit for default behavior
+            (which only shows regular comments).
+          schema:
+            title: ''
+            type: string
+            enum:
+              - notes
+              - comments
       responses:
         '200':
           description: 'List of comments'
@@ -745,6 +806,43 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
         - comments
+    post:
+      summary: Create a maintainer note in the patch
+      description: |
+        Create a maintainer note in the patch
+      operationId: patch_maintainer_note_create
+      requestBody:
+        $ref: '#/components/requestBodies/MaintainerNote'
+      responses:
+        '201':
+          description: 'Created maintainer note'
+          headers:
+            Link:
+              $ref: '#/components/headers/Link'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Comment'
+        '400':
+          description: 'Invalid request'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMaintainerNote'
+        '403':
+          description: 'Forbidden'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: 'Not found'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      tags:
+        - comments
   /api/patches/{patch_id}/comments/{comment_id}:
     parameters:
       - in: path
@@ -762,7 +860,7 @@ paths:
           title: Comment ID
           type: integer
     get:
-      summary: Show a patch comment.
+      summary: Show a patch comment or maintainer note.
       description: |
         Retrieve a patch comment by its ID and the ID of the patch.
       operationId: patch_comments_read
@@ -782,7 +880,7 @@ paths:
       tags:
         - comments
     patch:
-      summary: Update a patch comment (partial).
+      summary: Update a patch comment or mantainer note (partial).
       description:
         Partially update an existing patch comment.
         You must be a maintainer of the project that the patch comment belongs to.
@@ -1478,6 +1576,14 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/CommentUpdate'
+    MaintainerNote:
+      required: true
+      description: |
+        A maintainer note for patch or cover letters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/MaintainerNote'
     Patch:
       required: true
       description: |
@@ -1770,7 +1876,6 @@ components:
           title: Message ID
           type: string
           readOnly: true
-          minLength: 1
           maxLength: 255
         list_archive_url:
           title: List archive URL
@@ -1801,7 +1906,6 @@ components:
         content:
           title: Content
           type: string
-          readOnly: true
           minLength: 1
         headers:
           title: Headers
@@ -1831,6 +1935,21 @@ components:
           type:
             - 'null'
             - 'boolean'
+    MaintainerNote:
+      type: object
+      title: Maintainer note
+      description: |
+        The fields to set on a maintainer note.
+      properties:
+        content:
+          title: Content
+          type:
+            - 'string'
+        addressed:
+          title: Addressed
+          type:
+            - 'null'
+            - 'boolean'
     CoverList:
       type: object
       title: Cover letters
@@ -3153,6 +3272,22 @@ components:
           type: array
           items:
             type: string
+    ErrorMaintainerNote:
+      type: object
+      title: A maintainer note create or update error.
+      description: |
+        A mapping of field names to validation failures.
+      properties:
+        content:
+          title: Content
+          type: array
+          items:
+            type: string
+        addressed:
+          title: Addressed
+          type: array
+          items:
+            type: string
     ErrorPatchUpdate:
       type: object
       title: A patch update error.