openapi: Add component descriptions

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 c993756bd5c95a874c53c4bd1c96e36a400b965c..386f93a774aec98478ed7f5c31cd8756d47ff094 100644 (file)
--- a/docs/api/schemas/latest/patchwork.yaml
+++ b/docs/api/schemas/latest/patchwork.yaml
@@ -1299,6 +1299,8 @@ components:
     basicAuth:
       type: http
       scheme: basic
+      description: |
+        Basic authentication. This should be avoided and may be removed in a future API release.
     apiKeyAuth:
       type: http
       scheme: token
@@ -1368,6 +1370,8 @@ components:
   requestBodies:
     Bundle:
       required: true
+      description: |
+        A patch bundle.
       content:
         application/json:
           schema:
@@ -1380,6 +1384,8 @@ components:
             $ref: '#/components/schemas/BundleCreateUpdate'
     Check:
       required: true
+      description: |
+        A patch check.
       content:
         application/json:
           schema:
@@ -1392,12 +1398,16 @@ components:
             $ref: '#/components/schemas/CheckCreate'
     Comment:
       required: true
+      description: |
+        A patch or cover letter comment.
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/CommentUpdate'
     Patch:
       required: true
+      description: |
+        A patch.
       content:
         application/json:
           schema:
@@ -1410,6 +1420,8 @@ components:
             $ref: '#/components/schemas/PatchUpdate'
     Project:
       required: true
+      description: |
+        A project.
       content:
         application/json:
           schema:
@@ -1422,6 +1434,8 @@ components:
             $ref: '#/components/schemas/Project'
     User:
       required: true
+      description: |
+        A user.
       content:
         application/json:
           schema:
@@ -1435,6 +1449,9 @@ components:
   schemas:
     Index:
       type: object
+      name: Index
+      description: |
+        Paths to resource APIs
       properties:
         bundles:
           title: Bundles URL
@@ -1480,6 +1497,9 @@ components:
       required:
         - name
       type: object
+      title: Bundle
+      description: |
+        A patch bundle
       properties:
         id:
           title: ID
@@ -1530,6 +1550,9 @@ components:
           readOnly: true
     BundleCreateUpdate:
       type: object
+      title: Bundle create or update
+      description: |
+        The fields to set on a new or existing bundle.
       required:
         - name
       properties:
@@ -1549,6 +1572,9 @@ components:
           type: boolean
     Check:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -1604,6 +1630,9 @@ components:
             - 'string'
     CheckCreate:
       type: object
+      title: Check
+      description: |
+        A patch check
       required:
        - state
       properties:
@@ -1645,6 +1674,9 @@ components:
             - 'string'
     Comment:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -1716,6 +1748,9 @@ components:
             - 'boolean'
     CommentUpdate:
       type: object
+      title: Comment update
+      description: |
+        The fields to set on an existing comment.
       properties:
         addressed:
           title: Addressed
@@ -1724,6 +1759,9 @@ components:
             - 'boolean'
     CoverList:
       type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       properties:
         id:
           title: ID
@@ -1793,6 +1831,10 @@ components:
           format: uri
           readOnly: true
     CoverDetail:
+      type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       allOf:
         - $ref: '#/components/schemas/CoverList'
         - type: object
@@ -1816,6 +1858,9 @@ components:
               minLength: 1
     EventBase:
       type: object
+      title: Event base
+      description: |
+        Base event. Not directly used.
       properties:
         id:
           title: ID
@@ -1847,6 +1892,9 @@ components:
         payload:
           type: object
     EventCoverCreated:
+      title: Cover created event
+      description: |
+        A cover created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1859,6 +1907,9 @@ components:
                 cover:
                   $ref: '#/components/schemas/CoverEmbedded'
     EventPatchCreated:
+      title: Patch created event
+      description: |
+        A patch created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1871,6 +1922,9 @@ components:
                 patch:
                   $ref: '#/components/schemas/PatchEmbedded'
     EventPatchCompleted:
+      title: Patch completed event
+      description: |
+        A patch completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1885,6 +1939,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventPatchStateChanged:
+      title: Patch state change event
+      description: |
+        A patch state changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1903,6 +1960,9 @@ components:
                   title: Current state
                   type: string
     EventPatchRelationChanged:
+      title: Patch relation change event
+      description: |
+        A patch relation changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1925,6 +1985,9 @@ components:
                     - 'null'
                     - 'string'
     EventPatchDelegated:
+      title: Patch delegated event
+      description: |
+        A patch delegated event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1941,6 +2004,9 @@ components:
                 current_delegate:
                   $ref: '#/components/schemas/UserEmbedded'
     EventCheckCreated:
+      title: Check create event
+      description: |
+        A check created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1955,6 +2021,9 @@ components:
                 check:
                   $ref: '#/components/schemas/CheckEmbedded'
     EventSeriesCreated:
+      title: Series create event
+      description: |
+        A series created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1967,6 +2036,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventSeriesCompleted:
+      title: Series completed event
+      description: |
+        A series completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1979,6 +2051,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventCoverCommentCreated:
+      title: Cover letter comment create event
+      description: |
+        A comment letter comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1993,6 +2068,9 @@ components:
                 comment:
                   $ref: '#/components/schemas/CommentEmbedded'
     EventPatchCommentCreated:
+      title: Patch comment create event
+      description: |
+        A patch comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2011,6 +2089,9 @@ components:
         - state
         - delegate
       type: object
+      title: Patches
+      description: |
+        A list of patches.
       properties:
         id:
           title: ID
@@ -2146,6 +2227,10 @@ components:
           items:
             $ref: '#/components/schemas/PatchEmbedded'
     PatchDetail:
+      type: object
+      title: Patches
+      description: |
+        A list of patches.
       allOf:
         - $ref: '#/components/schemas/PatchList'
         - type: object
@@ -2180,6 +2265,9 @@ components:
               readOnly: true
     PatchUpdate:
       type: object
+      title: Patch update
+      description: |
+        The fields to set on an existing patch.
       properties:
         commit_ref:
           title: Commit ref
@@ -2218,6 +2306,9 @@ components:
             type: integer
     Person:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2252,6 +2343,9 @@ components:
             - $ref: '#/components/schemas/UserEmbedded'
     Project:
       type: object
+      title: Project
+      description: |
+        A project.
       properties:
         id:
           title: ID
@@ -2347,6 +2441,9 @@ components:
           type: string
     Series:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2424,6 +2521,9 @@ components:
           uniqueItems: true
     User:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2456,6 +2556,9 @@ components:
           minLength: 1
     UserDetail:
       type: object
+      title: User
+      description: |
+        A user
       allOf:
         - $ref: '#/components/schemas/User'
         - type: object
@@ -2483,6 +2586,9 @@ components:
                   type: boolean
     CheckEmbedded:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -2533,6 +2639,9 @@ components:
           readOnly: true
     CommentEmbedded:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -2571,6 +2680,9 @@ components:
           minLength: 1
     CoverEmbedded:
       type: object
+      title: Cover letter
+      description: |
+        A cover letter
       properties:
         id:
           title: ID
@@ -2616,6 +2728,9 @@ components:
           readOnly: true
     PatchEmbedded:
       type: object
+      title: Patch
+      description: |
+        A patch
       properties:
         id:
           title: ID
@@ -2663,6 +2778,9 @@ components:
           readOnly: true
     PersonEmbedded:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2686,6 +2804,9 @@ components:
           minLength: 1
     ProjectEmbedded:
       type: object
+      title: Project
+      description: |
+        A project
       properties:
         id:
           title: ID
@@ -2767,6 +2888,9 @@ components:
           readOnly: true
     SeriesEmbedded:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2815,6 +2939,9 @@ components:
           readOnly: true
     UserEmbedded:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2849,6 +2976,9 @@ components:
           minLength: 1
     Error:
       type: object
+      title: A generic error.
+      description: |
+        A generic error.
       properties:
         detail:
           title: Detail
@@ -2856,6 +2986,9 @@ components:
           readOnly: true
     ErrorBundleCreateUpdate:
       type: object
+      title: A bundle creation or update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         name:
           title: Name
@@ -2876,6 +3009,9 @@ components:
             type: string
     ErrorCheckCreate:
       type: object
+      title: A check creation error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2903,6 +3039,9 @@ components:
           readOnly: true
     ErrorCommentUpdate:
       type: object
+      title: A comment update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         addressed:
           title: Addressed
@@ -2911,6 +3050,9 @@ components:
             type: string
     ErrorPatchUpdate:
       type: object
+      title: A patch update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2938,6 +3080,9 @@ components:
           readOnly: true
     ErrorProjectUpdate:
       type: object
+      title: A project update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         web_url:
           title: Web URL
@@ -2956,6 +3101,9 @@ components:
           readOnly: true
     ErrorUserUpdate:
       type: object
+      title: A user update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         first_name:
           title: First name

diff --git a/docs/api/schemas/patchwork.j2 b/docs/api/schemas/patchwork.j2
index 2736779c45dcf1a54e47229fd109cd20cdd12270..ffc804fc73749d967609e1db5df4c0ebcd44aea4 100644 (file)
--- a/docs/api/schemas/patchwork.j2
+++ b/docs/api/schemas/patchwork.j2
@@ -1336,6 +1336,8 @@ components:
     basicAuth:
       type: http
       scheme: basic
+      description: |
+        Basic authentication. This should be avoided and may be removed in a future API release.
     apiKeyAuth:
       type: http
       scheme: token
@@ -1406,6 +1408,8 @@ components:
 {% if version >= (1, 2) %}
     Bundle:
       required: true
+      description: |
+        A patch bundle.
       content:
         application/json:
           schema:
@@ -1419,6 +1423,8 @@ components:
 {% endif %}
     Check:
       required: true
+      description: |
+        A patch check.
       content:
         application/json:
           schema:
@@ -1432,6 +1438,8 @@ components:
 {% if version >= (1, 3) %}
     Comment:
       required: true
+      description: |
+        A patch or cover letter comment.
       content:
         application/json:
           schema:
@@ -1439,6 +1447,8 @@ components:
 {% endif %}
     Patch:
       required: true
+      description: |
+        A patch.
       content:
         application/json:
           schema:
@@ -1451,6 +1461,8 @@ components:
             $ref: '#/components/schemas/PatchUpdate'
     Project:
       required: true
+      description: |
+        A project.
       content:
         application/json:
           schema:
@@ -1463,6 +1475,8 @@ components:
             $ref: '#/components/schemas/Project'
     User:
       required: true
+      description: |
+        A user.
       content:
         application/json:
           schema:
@@ -1488,6 +1502,9 @@ components:
   schemas:
     Index:
       type: object
+      name: Index
+      description: |
+        Paths to resource APIs
       properties:
         bundles:
           title: Bundles URL
@@ -1533,6 +1550,9 @@ components:
       required:
         - name
       type: object
+      title: Bundle
+      description: |
+        A patch bundle
       properties:
         id:
           title: ID
@@ -1589,6 +1609,9 @@ components:
 {% if version >= (1, 2) %}
     BundleCreateUpdate:
       type: object
+      title: Bundle create or update
+      description: |
+        The fields to set on a new or existing bundle.
       required:
         - name
       properties:
@@ -1609,6 +1632,9 @@ components:
 {% endif %}
     Check:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -1664,6 +1690,9 @@ components:
             - 'string'
     CheckCreate:
       type: object
+      title: Check
+      description: |
+        A patch check
       required:
        - state
       properties:
@@ -1705,6 +1734,9 @@ components:
             - 'string'
     Comment:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -1783,6 +1815,9 @@ components:
             - 'boolean'
     CommentUpdate:
       type: object
+      title: Comment update
+      description: |
+        The fields to set on an existing comment.
       properties:
         addressed:
           title: Addressed
@@ -1792,6 +1827,9 @@ components:
 {% endif %}
     CoverList:
       type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       properties:
         id:
           title: ID
@@ -1869,6 +1907,10 @@ components:
           readOnly: true
 {% endif %}
     CoverDetail:
+      type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       allOf:
         - $ref: '#/components/schemas/CoverList'
         - type: object
@@ -1892,6 +1934,9 @@ components:
               minLength: 1
     EventBase:
       type: object
+      title: Event base
+      description: |
+        Base event. Not directly used.
       properties:
         id:
           title: ID
@@ -1925,6 +1970,9 @@ components:
         payload:
           type: object
     EventCoverCreated:
+      title: Cover created event
+      description: |
+        A cover created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1937,6 +1985,9 @@ components:
                 cover:
                   $ref: '#/components/schemas/CoverEmbedded'
     EventPatchCreated:
+      title: Patch created event
+      description: |
+        A patch created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1949,6 +2000,9 @@ components:
                 patch:
                   $ref: '#/components/schemas/PatchEmbedded'
     EventPatchCompleted:
+      title: Patch completed event
+      description: |
+        A patch completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1963,6 +2017,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventPatchStateChanged:
+      title: Patch state change event
+      description: |
+        A patch state changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1981,6 +2038,9 @@ components:
                   title: Current state
                   type: string
     EventPatchRelationChanged:
+      title: Patch relation change event
+      description: |
+        A patch relation changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2003,6 +2063,9 @@ components:
                     - 'null'
                     - 'string'
     EventPatchDelegated:
+      title: Patch delegated event
+      description: |
+        A patch delegated event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2019,6 +2082,9 @@ components:
                 current_delegate:
                   $ref: '#/components/schemas/UserEmbedded'
     EventCheckCreated:
+      title: Check create event
+      description: |
+        A check created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2033,6 +2099,9 @@ components:
                 check:
                   $ref: '#/components/schemas/CheckEmbedded'
     EventSeriesCreated:
+      title: Series create event
+      description: |
+        A series created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2045,6 +2114,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventSeriesCompleted:
+      title: Series completed event
+      description: |
+        A series completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2057,6 +2129,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventCoverCommentCreated:
+      title: Cover letter comment create event
+      description: |
+        A comment letter comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2071,6 +2146,9 @@ components:
                 comment:
                   $ref: '#/components/schemas/CommentEmbedded'
     EventPatchCommentCreated:
+      title: Patch comment create event
+      description: |
+        A patch comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2089,6 +2167,9 @@ components:
         - state
         - delegate
       type: object
+      title: Patches
+      description: |
+        A list of patches.
       properties:
         id:
           title: ID
@@ -2232,6 +2313,10 @@ components:
             $ref: '#/components/schemas/PatchEmbedded'
 {% endif %}
     PatchDetail:
+      type: object
+      title: Patches
+      description: |
+        A list of patches.
       allOf:
         - $ref: '#/components/schemas/PatchList'
         - type: object
@@ -2266,6 +2351,9 @@ components:
               readOnly: true
     PatchUpdate:
       type: object
+      title: Patch update
+      description: |
+        The fields to set on an existing patch.
       properties:
         commit_ref:
           title: Commit ref
@@ -2306,6 +2394,9 @@ components:
 {% endif %}
     Person:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2340,6 +2431,9 @@ components:
             - $ref: '#/components/schemas/UserEmbedded'
     Project:
       type: object
+      title: Project
+      description: |
+        A project.
       properties:
         id:
           title: ID
@@ -2439,6 +2533,9 @@ components:
 {% endif %}
     Series:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2518,6 +2615,9 @@ components:
           uniqueItems: true
     User:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2551,6 +2651,9 @@ components:
 {% if version >= (1, 2) %}
     UserDetail:
       type: object
+      title: User
+      description: |
+        A user
       allOf:
         - $ref: '#/components/schemas/User'
         - type: object
@@ -2579,6 +2682,9 @@ components:
 {% endif %}
     CheckEmbedded:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -2629,6 +2735,9 @@ components:
           readOnly: true
     CommentEmbedded:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -2673,6 +2782,9 @@ components:
           minLength: 1
     CoverEmbedded:
       type: object
+      title: Cover letter
+      description: |
+        A cover letter
       properties:
         id:
           title: ID
@@ -2722,6 +2834,9 @@ components:
           readOnly: true
     PatchEmbedded:
       type: object
+      title: Patch
+      description: |
+        A patch
       properties:
         id:
           title: ID
@@ -2773,6 +2888,9 @@ components:
           readOnly: true
     PersonEmbedded:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2796,6 +2914,9 @@ components:
           minLength: 1
     ProjectEmbedded:
       type: object
+      title: Project
+      description: |
+        A project
       properties:
         id:
           title: ID
@@ -2879,6 +3000,9 @@ components:
 {% endif %}
     SeriesEmbedded:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2929,6 +3053,9 @@ components:
           readOnly: true
     UserEmbedded:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2963,6 +3090,9 @@ components:
           minLength: 1
     Error:
       type: object
+      title: A generic error.
+      description: |
+        A generic error.
       properties:
         detail:
           title: Detail
@@ -2971,6 +3101,9 @@ components:
 {% if version >= (1, 2) %}
     ErrorBundleCreateUpdate:
       type: object
+      title: A bundle creation or update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         name:
           title: Name
@@ -2992,6 +3125,9 @@ components:
 {% endif %}
     ErrorCheckCreate:
       type: object
+      title: A check creation error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -3020,6 +3156,9 @@ components:
 {% if version >= (1, 3) %}
     ErrorCommentUpdate:
       type: object
+      title: A comment update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         addressed:
           title: Addressed
@@ -3029,6 +3168,9 @@ components:
 {% endif %}
     ErrorPatchUpdate:
       type: object
+      title: A patch update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -3056,6 +3198,9 @@ components:
           readOnly: true
     ErrorProjectUpdate:
       type: object
+      title: A project update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         web_url:
           title: Web URL
@@ -3074,6 +3219,9 @@ components:
           readOnly: true
     ErrorUserUpdate:
       type: object
+      title: A user update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         first_name:
           title: First name

diff --git a/docs/api/schemas/v1.0/patchwork.yaml b/docs/api/schemas/v1.0/patchwork.yaml
index 894304bf50f96c452279233ecbb931b0d0641366..7c0981cb5b02a6b77ecf9109ec98f5d366de4acd 100644 (file)
--- a/docs/api/schemas/v1.0/patchwork.yaml
+++ b/docs/api/schemas/v1.0/patchwork.yaml
@@ -1030,6 +1030,8 @@ components:
     basicAuth:
       type: http
       scheme: basic
+      description: |
+        Basic authentication. This should be avoided and may be removed in a future API release.
     apiKeyAuth:
       type: http
       scheme: token
@@ -1099,6 +1101,8 @@ components:
   requestBodies:
     Check:
       required: true
+      description: |
+        A patch check.
       content:
         application/json:
           schema:
@@ -1111,6 +1115,8 @@ components:
             $ref: '#/components/schemas/CheckCreate'
     Patch:
       required: true
+      description: |
+        A patch.
       content:
         application/json:
           schema:
@@ -1123,6 +1129,8 @@ components:
             $ref: '#/components/schemas/PatchUpdate'
     Project:
       required: true
+      description: |
+        A project.
       content:
         application/json:
           schema:
@@ -1135,6 +1143,8 @@ components:
             $ref: '#/components/schemas/Project'
     User:
       required: true
+      description: |
+        A user.
       content:
         application/json:
           schema:
@@ -1148,6 +1158,9 @@ components:
   schemas:
     Index:
       type: object
+      name: Index
+      description: |
+        Paths to resource APIs
       properties:
         bundles:
           title: Bundles URL
@@ -1193,6 +1206,9 @@ components:
       required:
         - name
       type: object
+      title: Bundle
+      description: |
+        A patch bundle
       properties:
         id:
           title: ID
@@ -1239,6 +1255,9 @@ components:
           readOnly: true
     Check:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -1294,6 +1313,9 @@ components:
             - 'string'
     CheckCreate:
       type: object
+      title: Check
+      description: |
+        A patch check
       required:
        - state
       properties:
@@ -1335,6 +1357,9 @@ components:
             - 'string'
     Comment:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -1380,6 +1405,9 @@ components:
           readOnly: true
     CoverList:
       type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       properties:
         id:
           title: ID
@@ -1421,6 +1449,10 @@ components:
             $ref: '#/components/schemas/SeriesEmbedded'
           readOnly: true
     CoverDetail:
+      type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       allOf:
         - $ref: '#/components/schemas/CoverList'
         - type: object
@@ -1444,6 +1476,9 @@ components:
               minLength: 1
     EventBase:
       type: object
+      title: Event base
+      description: |
+        Base event. Not directly used.
       properties:
         id:
           title: ID
@@ -1465,6 +1500,9 @@ components:
         payload:
           type: object
     EventCoverCreated:
+      title: Cover created event
+      description: |
+        A cover created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1477,6 +1515,9 @@ components:
                 cover:
                   $ref: '#/components/schemas/CoverEmbedded'
     EventPatchCreated:
+      title: Patch created event
+      description: |
+        A patch created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1489,6 +1530,9 @@ components:
                 patch:
                   $ref: '#/components/schemas/PatchEmbedded'
     EventPatchCompleted:
+      title: Patch completed event
+      description: |
+        A patch completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1503,6 +1547,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventPatchStateChanged:
+      title: Patch state change event
+      description: |
+        A patch state changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1521,6 +1568,9 @@ components:
                   title: Current state
                   type: string
     EventPatchRelationChanged:
+      title: Patch relation change event
+      description: |
+        A patch relation changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1543,6 +1593,9 @@ components:
                     - 'null'
                     - 'string'
     EventPatchDelegated:
+      title: Patch delegated event
+      description: |
+        A patch delegated event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1559,6 +1612,9 @@ components:
                 current_delegate:
                   $ref: '#/components/schemas/UserEmbedded'
     EventCheckCreated:
+      title: Check create event
+      description: |
+        A check created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1573,6 +1629,9 @@ components:
                 check:
                   $ref: '#/components/schemas/CheckEmbedded'
     EventSeriesCreated:
+      title: Series create event
+      description: |
+        A series created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1585,6 +1644,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventSeriesCompleted:
+      title: Series completed event
+      description: |
+        A series completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1597,6 +1659,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventCoverCommentCreated:
+      title: Cover letter comment create event
+      description: |
+        A comment letter comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1611,6 +1676,9 @@ components:
                 comment:
                   $ref: '#/components/schemas/CommentEmbedded'
     EventPatchCommentCreated:
+      title: Patch comment create event
+      description: |
+        A patch comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1629,6 +1697,9 @@ components:
         - state
         - delegate
       type: object
+      title: Patches
+      description: |
+        A list of patches.
       properties:
         id:
           title: ID
@@ -1738,6 +1809,10 @@ components:
             type: string
           readOnly: true
     PatchDetail:
+      type: object
+      title: Patches
+      description: |
+        A list of patches.
       allOf:
         - $ref: '#/components/schemas/PatchList'
         - type: object
@@ -1772,6 +1847,9 @@ components:
               readOnly: true
     PatchUpdate:
       type: object
+      title: Patch update
+      description: |
+        The fields to set on an existing patch.
       properties:
         commit_ref:
           title: Commit ref
@@ -1805,6 +1883,9 @@ components:
             - 'integer'
     Person:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -1839,6 +1920,9 @@ components:
             - $ref: '#/components/schemas/UserEmbedded'
     Project:
       type: object
+      title: Project
+      description: |
+        A project.
       properties:
         id:
           title: ID
@@ -1897,6 +1981,9 @@ components:
           uniqueItems: true
     Series:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -1969,6 +2056,9 @@ components:
           uniqueItems: true
     User:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2001,6 +2091,9 @@ components:
           minLength: 1
     CheckEmbedded:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -2051,6 +2144,9 @@ components:
           readOnly: true
     CommentEmbedded:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -2073,6 +2169,9 @@ components:
           minLength: 1
     CoverEmbedded:
       type: object
+      title: Cover letter
+      description: |
+        A cover letter
       properties:
         id:
           title: ID
@@ -2107,6 +2206,9 @@ components:
           readOnly: true
     PatchEmbedded:
       type: object
+      title: Patch
+      description: |
+        A patch
       properties:
         id:
           title: ID
@@ -2143,6 +2245,9 @@ components:
           readOnly: true
     PersonEmbedded:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2166,6 +2271,9 @@ components:
           minLength: 1
     ProjectEmbedded:
       type: object
+      title: Project
+      description: |
+        A project
       properties:
         id:
           title: ID
@@ -2220,6 +2328,9 @@ components:
           maxLength: 2000
     SeriesEmbedded:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2263,6 +2374,9 @@ components:
           readOnly: true
     UserEmbedded:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2297,6 +2411,9 @@ components:
           minLength: 1
     Error:
       type: object
+      title: A generic error.
+      description: |
+        A generic error.
       properties:
         detail:
           title: Detail
@@ -2304,6 +2421,9 @@ components:
           readOnly: true
     ErrorCheckCreate:
       type: object
+      title: A check creation error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2331,6 +2451,9 @@ components:
           readOnly: true
     ErrorPatchUpdate:
       type: object
+      title: A patch update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2358,6 +2481,9 @@ components:
           readOnly: true
     ErrorProjectUpdate:
       type: object
+      title: A project update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         web_url:
           title: Web URL
@@ -2376,6 +2502,9 @@ components:
           readOnly: true
     ErrorUserUpdate:
       type: object
+      title: A user update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         first_name:
           title: First name

diff --git a/docs/api/schemas/v1.1/patchwork.yaml b/docs/api/schemas/v1.1/patchwork.yaml
index f35b47587288687e096f59768734b0e366fcb4d7..f62dfbe7ece8d829156df870008c299da3102535 100644 (file)
--- a/docs/api/schemas/v1.1/patchwork.yaml
+++ b/docs/api/schemas/v1.1/patchwork.yaml
@@ -1030,6 +1030,8 @@ components:
     basicAuth:
       type: http
       scheme: basic
+      description: |
+        Basic authentication. This should be avoided and may be removed in a future API release.
     apiKeyAuth:
       type: http
       scheme: token
@@ -1099,6 +1101,8 @@ components:
   requestBodies:
     Check:
       required: true
+      description: |
+        A patch check.
       content:
         application/json:
           schema:
@@ -1111,6 +1115,8 @@ components:
             $ref: '#/components/schemas/CheckCreate'
     Patch:
       required: true
+      description: |
+        A patch.
       content:
         application/json:
           schema:
@@ -1123,6 +1129,8 @@ components:
             $ref: '#/components/schemas/PatchUpdate'
     Project:
       required: true
+      description: |
+        A project.
       content:
         application/json:
           schema:
@@ -1135,6 +1143,8 @@ components:
             $ref: '#/components/schemas/Project'
     User:
       required: true
+      description: |
+        A user.
       content:
         application/json:
           schema:
@@ -1148,6 +1158,9 @@ components:
   schemas:
     Index:
       type: object
+      name: Index
+      description: |
+        Paths to resource APIs
       properties:
         bundles:
           title: Bundles URL
@@ -1193,6 +1206,9 @@ components:
       required:
         - name
       type: object
+      title: Bundle
+      description: |
+        A patch bundle
       properties:
         id:
           title: ID
@@ -1244,6 +1260,9 @@ components:
           readOnly: true
     Check:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -1299,6 +1318,9 @@ components:
             - 'string'
     CheckCreate:
       type: object
+      title: Check
+      description: |
+        A patch check
       required:
        - state
       properties:
@@ -1340,6 +1362,9 @@ components:
             - 'string'
     Comment:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -1390,6 +1415,9 @@ components:
           readOnly: true
     CoverList:
       type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       properties:
         id:
           title: ID
@@ -1448,6 +1476,10 @@ components:
           format: uri
           readOnly: true
     CoverDetail:
+      type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       allOf:
         - $ref: '#/components/schemas/CoverList'
         - type: object
@@ -1471,6 +1503,9 @@ components:
               minLength: 1
     EventBase:
       type: object
+      title: Event base
+      description: |
+        Base event. Not directly used.
       properties:
         id:
           title: ID
@@ -1492,6 +1527,9 @@ components:
         payload:
           type: object
     EventCoverCreated:
+      title: Cover created event
+      description: |
+        A cover created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1504,6 +1542,9 @@ components:
                 cover:
                   $ref: '#/components/schemas/CoverEmbedded'
     EventPatchCreated:
+      title: Patch created event
+      description: |
+        A patch created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1516,6 +1557,9 @@ components:
                 patch:
                   $ref: '#/components/schemas/PatchEmbedded'
     EventPatchCompleted:
+      title: Patch completed event
+      description: |
+        A patch completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1530,6 +1574,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventPatchStateChanged:
+      title: Patch state change event
+      description: |
+        A patch state changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1548,6 +1595,9 @@ components:
                   title: Current state
                   type: string
     EventPatchRelationChanged:
+      title: Patch relation change event
+      description: |
+        A patch relation changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1570,6 +1620,9 @@ components:
                     - 'null'
                     - 'string'
     EventPatchDelegated:
+      title: Patch delegated event
+      description: |
+        A patch delegated event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1586,6 +1639,9 @@ components:
                 current_delegate:
                   $ref: '#/components/schemas/UserEmbedded'
     EventCheckCreated:
+      title: Check create event
+      description: |
+        A check created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1600,6 +1656,9 @@ components:
                 check:
                   $ref: '#/components/schemas/CheckEmbedded'
     EventSeriesCreated:
+      title: Series create event
+      description: |
+        A series created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1612,6 +1671,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventSeriesCompleted:
+      title: Series completed event
+      description: |
+        A series completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1624,6 +1686,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventCoverCommentCreated:
+      title: Cover letter comment create event
+      description: |
+        A comment letter comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1638,6 +1703,9 @@ components:
                 comment:
                   $ref: '#/components/schemas/CommentEmbedded'
     EventPatchCommentCreated:
+      title: Patch comment create event
+      description: |
+        A patch comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1656,6 +1724,9 @@ components:
         - state
         - delegate
       type: object
+      title: Patches
+      description: |
+        A list of patches.
       properties:
         id:
           title: ID
@@ -1775,6 +1846,10 @@ components:
             type: string
           readOnly: true
     PatchDetail:
+      type: object
+      title: Patches
+      description: |
+        A list of patches.
       allOf:
         - $ref: '#/components/schemas/PatchList'
         - type: object
@@ -1809,6 +1884,9 @@ components:
               readOnly: true
     PatchUpdate:
       type: object
+      title: Patch update
+      description: |
+        The fields to set on an existing patch.
       properties:
         commit_ref:
           title: Commit ref
@@ -1842,6 +1920,9 @@ components:
             - 'integer'
     Person:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -1876,6 +1957,9 @@ components:
             - $ref: '#/components/schemas/UserEmbedded'
     Project:
       type: object
+      title: Project
+      description: |
+        A project.
       properties:
         id:
           title: ID
@@ -1945,6 +2029,9 @@ components:
           maxLength: 64
     Series:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2022,6 +2109,9 @@ components:
           uniqueItems: true
     User:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2054,6 +2144,9 @@ components:
           minLength: 1
     CheckEmbedded:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -2104,6 +2197,9 @@ components:
           readOnly: true
     CommentEmbedded:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -2131,6 +2227,9 @@ components:
           minLength: 1
     CoverEmbedded:
       type: object
+      title: Cover letter
+      description: |
+        A cover letter
       properties:
         id:
           title: ID
@@ -2170,6 +2269,9 @@ components:
           readOnly: true
     PatchEmbedded:
       type: object
+      title: Patch
+      description: |
+        A patch
       properties:
         id:
           title: ID
@@ -2211,6 +2313,9 @@ components:
           readOnly: true
     PersonEmbedded:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2234,6 +2339,9 @@ components:
           minLength: 1
     ProjectEmbedded:
       type: object
+      title: Project
+      description: |
+        A project
       properties:
         id:
           title: ID
@@ -2288,6 +2396,9 @@ components:
           maxLength: 2000
     SeriesEmbedded:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2336,6 +2447,9 @@ components:
           readOnly: true
     UserEmbedded:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2370,6 +2484,9 @@ components:
           minLength: 1
     Error:
       type: object
+      title: A generic error.
+      description: |
+        A generic error.
       properties:
         detail:
           title: Detail
@@ -2377,6 +2494,9 @@ components:
           readOnly: true
     ErrorCheckCreate:
       type: object
+      title: A check creation error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2404,6 +2524,9 @@ components:
           readOnly: true
     ErrorPatchUpdate:
       type: object
+      title: A patch update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2431,6 +2554,9 @@ components:
           readOnly: true
     ErrorProjectUpdate:
       type: object
+      title: A project update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         web_url:
           title: Web URL
@@ -2449,6 +2575,9 @@ components:
           readOnly: true
     ErrorUserUpdate:
       type: object
+      title: A user update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         first_name:
           title: First name

diff --git a/docs/api/schemas/v1.2/patchwork.yaml b/docs/api/schemas/v1.2/patchwork.yaml
index 3fb4be7ce4ec3cf667ea24462d01206179a1ffd1..531f6bc062208b53d9a28cd0899f813214309248 100644 (file)
--- a/docs/api/schemas/v1.2/patchwork.yaml
+++ b/docs/api/schemas/v1.2/patchwork.yaml
@@ -1165,6 +1165,8 @@ components:
     basicAuth:
       type: http
       scheme: basic
+      description: |
+        Basic authentication. This should be avoided and may be removed in a future API release.
     apiKeyAuth:
       type: http
       scheme: token
@@ -1234,6 +1236,8 @@ components:
   requestBodies:
     Bundle:
       required: true
+      description: |
+        A patch bundle.
       content:
         application/json:
           schema:
@@ -1246,6 +1250,8 @@ components:
             $ref: '#/components/schemas/BundleCreateUpdate'
     Check:
       required: true
+      description: |
+        A patch check.
       content:
         application/json:
           schema:
@@ -1258,6 +1264,8 @@ components:
             $ref: '#/components/schemas/CheckCreate'
     Patch:
       required: true
+      description: |
+        A patch.
       content:
         application/json:
           schema:
@@ -1270,6 +1278,8 @@ components:
             $ref: '#/components/schemas/PatchUpdate'
     Project:
       required: true
+      description: |
+        A project.
       content:
         application/json:
           schema:
@@ -1282,6 +1292,8 @@ components:
             $ref: '#/components/schemas/Project'
     User:
       required: true
+      description: |
+        A user.
       content:
         application/json:
           schema:
@@ -1295,6 +1307,9 @@ components:
   schemas:
     Index:
       type: object
+      name: Index
+      description: |
+        Paths to resource APIs
       properties:
         bundles:
           title: Bundles URL
@@ -1340,6 +1355,9 @@ components:
       required:
         - name
       type: object
+      title: Bundle
+      description: |
+        A patch bundle
       properties:
         id:
           title: ID
@@ -1390,6 +1408,9 @@ components:
           readOnly: true
     BundleCreateUpdate:
       type: object
+      title: Bundle create or update
+      description: |
+        The fields to set on a new or existing bundle.
       required:
         - name
       properties:
@@ -1409,6 +1430,9 @@ components:
           type: boolean
     Check:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -1464,6 +1488,9 @@ components:
             - 'string'
     CheckCreate:
       type: object
+      title: Check
+      description: |
+        A patch check
       required:
        - state
       properties:
@@ -1505,6 +1532,9 @@ components:
             - 'string'
     Comment:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -1566,6 +1596,9 @@ components:
           readOnly: true
     CoverList:
       type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       properties:
         id:
           title: ID
@@ -1635,6 +1668,10 @@ components:
           format: uri
           readOnly: true
     CoverDetail:
+      type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       allOf:
         - $ref: '#/components/schemas/CoverList'
         - type: object
@@ -1658,6 +1695,9 @@ components:
               minLength: 1
     EventBase:
       type: object
+      title: Event base
+      description: |
+        Base event. Not directly used.
       properties:
         id:
           title: ID
@@ -1689,6 +1729,9 @@ components:
         payload:
           type: object
     EventCoverCreated:
+      title: Cover created event
+      description: |
+        A cover created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1701,6 +1744,9 @@ components:
                 cover:
                   $ref: '#/components/schemas/CoverEmbedded'
     EventPatchCreated:
+      title: Patch created event
+      description: |
+        A patch created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1713,6 +1759,9 @@ components:
                 patch:
                   $ref: '#/components/schemas/PatchEmbedded'
     EventPatchCompleted:
+      title: Patch completed event
+      description: |
+        A patch completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1727,6 +1776,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventPatchStateChanged:
+      title: Patch state change event
+      description: |
+        A patch state changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1745,6 +1797,9 @@ components:
                   title: Current state
                   type: string
     EventPatchRelationChanged:
+      title: Patch relation change event
+      description: |
+        A patch relation changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1767,6 +1822,9 @@ components:
                     - 'null'
                     - 'string'
     EventPatchDelegated:
+      title: Patch delegated event
+      description: |
+        A patch delegated event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1783,6 +1841,9 @@ components:
                 current_delegate:
                   $ref: '#/components/schemas/UserEmbedded'
     EventCheckCreated:
+      title: Check create event
+      description: |
+        A check created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1797,6 +1858,9 @@ components:
                 check:
                   $ref: '#/components/schemas/CheckEmbedded'
     EventSeriesCreated:
+      title: Series create event
+      description: |
+        A series created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1809,6 +1873,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventSeriesCompleted:
+      title: Series completed event
+      description: |
+        A series completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1821,6 +1888,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventCoverCommentCreated:
+      title: Cover letter comment create event
+      description: |
+        A comment letter comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1835,6 +1905,9 @@ components:
                 comment:
                   $ref: '#/components/schemas/CommentEmbedded'
     EventPatchCommentCreated:
+      title: Patch comment create event
+      description: |
+        A patch comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1853,6 +1926,9 @@ components:
         - state
         - delegate
       type: object
+      title: Patches
+      description: |
+        A list of patches.
       properties:
         id:
           title: ID
@@ -1988,6 +2064,10 @@ components:
           items:
             $ref: '#/components/schemas/PatchEmbedded'
     PatchDetail:
+      type: object
+      title: Patches
+      description: |
+        A list of patches.
       allOf:
         - $ref: '#/components/schemas/PatchList'
         - type: object
@@ -2022,6 +2102,9 @@ components:
               readOnly: true
     PatchUpdate:
       type: object
+      title: Patch update
+      description: |
+        The fields to set on an existing patch.
       properties:
         commit_ref:
           title: Commit ref
@@ -2060,6 +2143,9 @@ components:
             type: integer
     Person:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2094,6 +2180,9 @@ components:
             - $ref: '#/components/schemas/UserEmbedded'
     Project:
       type: object
+      title: Project
+      description: |
+        A project.
       properties:
         id:
           title: ID
@@ -2189,6 +2278,9 @@ components:
           type: string
     Series:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2266,6 +2358,9 @@ components:
           uniqueItems: true
     User:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2298,6 +2393,9 @@ components:
           minLength: 1
     UserDetail:
       type: object
+      title: User
+      description: |
+        A user
       allOf:
         - $ref: '#/components/schemas/User'
         - type: object
@@ -2325,6 +2423,9 @@ components:
                   type: boolean
     CheckEmbedded:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -2375,6 +2476,9 @@ components:
           readOnly: true
     CommentEmbedded:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -2408,6 +2512,9 @@ components:
           minLength: 1
     CoverEmbedded:
       type: object
+      title: Cover letter
+      description: |
+        A cover letter
       properties:
         id:
           title: ID
@@ -2453,6 +2560,9 @@ components:
           readOnly: true
     PatchEmbedded:
       type: object
+      title: Patch
+      description: |
+        A patch
       properties:
         id:
           title: ID
@@ -2500,6 +2610,9 @@ components:
           readOnly: true
     PersonEmbedded:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2523,6 +2636,9 @@ components:
           minLength: 1
     ProjectEmbedded:
       type: object
+      title: Project
+      description: |
+        A project
       properties:
         id:
           title: ID
@@ -2604,6 +2720,9 @@ components:
           readOnly: true
     SeriesEmbedded:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2652,6 +2771,9 @@ components:
           readOnly: true
     UserEmbedded:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2686,6 +2808,9 @@ components:
           minLength: 1
     Error:
       type: object
+      title: A generic error.
+      description: |
+        A generic error.
       properties:
         detail:
           title: Detail
@@ -2693,6 +2818,9 @@ components:
           readOnly: true
     ErrorBundleCreateUpdate:
       type: object
+      title: A bundle creation or update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         name:
           title: Name
@@ -2713,6 +2841,9 @@ components:
             type: string
     ErrorCheckCreate:
       type: object
+      title: A check creation error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2740,6 +2871,9 @@ components:
           readOnly: true
     ErrorPatchUpdate:
       type: object
+      title: A patch update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2767,6 +2901,9 @@ components:
           readOnly: true
     ErrorProjectUpdate:
       type: object
+      title: A project update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         web_url:
           title: Web URL
@@ -2785,6 +2922,9 @@ components:
           readOnly: true
     ErrorUserUpdate:
       type: object
+      title: A user update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         first_name:
           title: First name

diff --git a/docs/api/schemas/v1.3/patchwork.yaml b/docs/api/schemas/v1.3/patchwork.yaml
index fa525b2db9a712ca10cd5580a82e06cdcb5f24bb..ff5d19f49f25ed15e6f4ff0eb3fd663e3828d369 100644 (file)
--- a/docs/api/schemas/v1.3/patchwork.yaml
+++ b/docs/api/schemas/v1.3/patchwork.yaml
@@ -1299,6 +1299,8 @@ components:
     basicAuth:
       type: http
       scheme: basic
+      description: |
+        Basic authentication. This should be avoided and may be removed in a future API release.
     apiKeyAuth:
       type: http
       scheme: token
@@ -1368,6 +1370,8 @@ components:
   requestBodies:
     Bundle:
       required: true
+      description: |
+        A patch bundle.
       content:
         application/json:
           schema:
@@ -1380,6 +1384,8 @@ components:
             $ref: '#/components/schemas/BundleCreateUpdate'
     Check:
       required: true
+      description: |
+        A patch check.
       content:
         application/json:
           schema:
@@ -1392,12 +1398,16 @@ components:
             $ref: '#/components/schemas/CheckCreate'
     Comment:
       required: true
+      description: |
+        A patch or cover letter comment.
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/CommentUpdate'
     Patch:
       required: true
+      description: |
+        A patch.
       content:
         application/json:
           schema:
@@ -1410,6 +1420,8 @@ components:
             $ref: '#/components/schemas/PatchUpdate'
     Project:
       required: true
+      description: |
+        A project.
       content:
         application/json:
           schema:
@@ -1422,6 +1434,8 @@ components:
             $ref: '#/components/schemas/Project'
     User:
       required: true
+      description: |
+        A user.
       content:
         application/json:
           schema:
@@ -1435,6 +1449,9 @@ components:
   schemas:
     Index:
       type: object
+      name: Index
+      description: |
+        Paths to resource APIs
       properties:
         bundles:
           title: Bundles URL
@@ -1480,6 +1497,9 @@ components:
       required:
         - name
       type: object
+      title: Bundle
+      description: |
+        A patch bundle
       properties:
         id:
           title: ID
@@ -1530,6 +1550,9 @@ components:
           readOnly: true
     BundleCreateUpdate:
       type: object
+      title: Bundle create or update
+      description: |
+        The fields to set on a new or existing bundle.
       required:
         - name
       properties:
@@ -1549,6 +1572,9 @@ components:
           type: boolean
     Check:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -1604,6 +1630,9 @@ components:
             - 'string'
     CheckCreate:
       type: object
+      title: Check
+      description: |
+        A patch check
       required:
        - state
       properties:
@@ -1645,6 +1674,9 @@ components:
             - 'string'
     Comment:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -1716,6 +1748,9 @@ components:
             - 'boolean'
     CommentUpdate:
       type: object
+      title: Comment update
+      description: |
+        The fields to set on an existing comment.
       properties:
         addressed:
           title: Addressed
@@ -1724,6 +1759,9 @@ components:
             - 'boolean'
     CoverList:
       type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       properties:
         id:
           title: ID
@@ -1793,6 +1831,10 @@ components:
           format: uri
           readOnly: true
     CoverDetail:
+      type: object
+      title: Cover letters
+      description: |
+        A list of cover letters
       allOf:
         - $ref: '#/components/schemas/CoverList'
         - type: object
@@ -1816,6 +1858,9 @@ components:
               minLength: 1
     EventBase:
       type: object
+      title: Event base
+      description: |
+        Base event. Not directly used.
       properties:
         id:
           title: ID
@@ -1847,6 +1892,9 @@ components:
         payload:
           type: object
     EventCoverCreated:
+      title: Cover created event
+      description: |
+        A cover created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1859,6 +1907,9 @@ components:
                 cover:
                   $ref: '#/components/schemas/CoverEmbedded'
     EventPatchCreated:
+      title: Patch created event
+      description: |
+        A patch created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1871,6 +1922,9 @@ components:
                 patch:
                   $ref: '#/components/schemas/PatchEmbedded'
     EventPatchCompleted:
+      title: Patch completed event
+      description: |
+        A patch completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1885,6 +1939,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventPatchStateChanged:
+      title: Patch state change event
+      description: |
+        A patch state changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1903,6 +1960,9 @@ components:
                   title: Current state
                   type: string
     EventPatchRelationChanged:
+      title: Patch relation change event
+      description: |
+        A patch relation changed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1925,6 +1985,9 @@ components:
                     - 'null'
                     - 'string'
     EventPatchDelegated:
+      title: Patch delegated event
+      description: |
+        A patch delegated event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1941,6 +2004,9 @@ components:
                 current_delegate:
                   $ref: '#/components/schemas/UserEmbedded'
     EventCheckCreated:
+      title: Check create event
+      description: |
+        A check created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1955,6 +2021,9 @@ components:
                 check:
                   $ref: '#/components/schemas/CheckEmbedded'
     EventSeriesCreated:
+      title: Series create event
+      description: |
+        A series created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1967,6 +2036,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventSeriesCompleted:
+      title: Series completed event
+      description: |
+        A series completed event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1979,6 +2051,9 @@ components:
                 series:
                   $ref: '#/components/schemas/SeriesEmbedded'
     EventCoverCommentCreated:
+      title: Cover letter comment create event
+      description: |
+        A comment letter comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -1993,6 +2068,9 @@ components:
                 comment:
                   $ref: '#/components/schemas/CommentEmbedded'
     EventPatchCommentCreated:
+      title: Patch comment create event
+      description: |
+        A patch comment created event.
       allOf:
         - $ref: '#/components/schemas/EventBase'
         - type: object
@@ -2011,6 +2089,9 @@ components:
         - state
         - delegate
       type: object
+      title: Patches
+      description: |
+        A list of patches.
       properties:
         id:
           title: ID
@@ -2146,6 +2227,10 @@ components:
           items:
             $ref: '#/components/schemas/PatchEmbedded'
     PatchDetail:
+      type: object
+      title: Patches
+      description: |
+        A list of patches.
       allOf:
         - $ref: '#/components/schemas/PatchList'
         - type: object
@@ -2180,6 +2265,9 @@ components:
               readOnly: true
     PatchUpdate:
       type: object
+      title: Patch update
+      description: |
+        The fields to set on an existing patch.
       properties:
         commit_ref:
           title: Commit ref
@@ -2218,6 +2306,9 @@ components:
             type: integer
     Person:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2252,6 +2343,9 @@ components:
             - $ref: '#/components/schemas/UserEmbedded'
     Project:
       type: object
+      title: Project
+      description: |
+        A project.
       properties:
         id:
           title: ID
@@ -2347,6 +2441,9 @@ components:
           type: string
     Series:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2424,6 +2521,9 @@ components:
           uniqueItems: true
     User:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2456,6 +2556,9 @@ components:
           minLength: 1
     UserDetail:
       type: object
+      title: User
+      description: |
+        A user
       allOf:
         - $ref: '#/components/schemas/User'
         - type: object
@@ -2483,6 +2586,9 @@ components:
                   type: boolean
     CheckEmbedded:
       type: object
+      title: Check
+      description: |
+        A patch check
       properties:
         id:
           title: ID
@@ -2533,6 +2639,9 @@ components:
           readOnly: true
     CommentEmbedded:
       type: object
+      title: Comment
+      description: |
+        A comment
       properties:
         id:
           title: ID
@@ -2571,6 +2680,9 @@ components:
           minLength: 1
     CoverEmbedded:
       type: object
+      title: Cover letter
+      description: |
+        A cover letter
       properties:
         id:
           title: ID
@@ -2616,6 +2728,9 @@ components:
           readOnly: true
     PatchEmbedded:
       type: object
+      title: Patch
+      description: |
+        A patch
       properties:
         id:
           title: ID
@@ -2663,6 +2778,9 @@ components:
           readOnly: true
     PersonEmbedded:
       type: object
+      title: Person
+      description: |
+        A person
       properties:
         id:
           title: ID
@@ -2686,6 +2804,9 @@ components:
           minLength: 1
     ProjectEmbedded:
       type: object
+      title: Project
+      description: |
+        A project
       properties:
         id:
           title: ID
@@ -2767,6 +2888,9 @@ components:
           readOnly: true
     SeriesEmbedded:
       type: object
+      title: Series
+      description: |
+        A series
       properties:
         id:
           title: ID
@@ -2815,6 +2939,9 @@ components:
           readOnly: true
     UserEmbedded:
       type: object
+      title: User
+      description: |
+        A user
       properties:
         id:
           title: ID
@@ -2849,6 +2976,9 @@ components:
           minLength: 1
     Error:
       type: object
+      title: A generic error.
+      description: |
+        A generic error.
       properties:
         detail:
           title: Detail
@@ -2856,6 +2986,9 @@ components:
           readOnly: true
     ErrorBundleCreateUpdate:
       type: object
+      title: A bundle creation or update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         name:
           title: Name
@@ -2876,6 +3009,9 @@ components:
             type: string
     ErrorCheckCreate:
       type: object
+      title: A check creation error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2903,6 +3039,9 @@ components:
           readOnly: true
     ErrorCommentUpdate:
       type: object
+      title: A comment update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         addressed:
           title: Addressed
@@ -2911,6 +3050,9 @@ components:
             type: string
     ErrorPatchUpdate:
       type: object
+      title: A patch update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         state:
           title: State
@@ -2938,6 +3080,9 @@ components:
           readOnly: true
     ErrorProjectUpdate:
       type: object
+      title: A project update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         web_url:
           title: Web URL
@@ -2956,6 +3101,9 @@ components:
           readOnly: true
     ErrorUserUpdate:
       type: object
+      title: A user update error.
+      description: |
+        A mapping of field names to validation failures.
       properties:
         first_name:
           title: First name