docs: Document the '/events' resource

This is the final resource to document and also the most complicated, on
account of the polymorphism of the responses. However, with this done,
our first pass at an OpenAPI 3.0 schema is completed.

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

1 files changed, 265 insertions, 0 deletions

diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml
index 915111e..875c120 100644
--- a/docs/api/schemas/patchwork.yaml
+++ b/docs/api/schemas/patchwork.yaml
@@ -199,6 +199,89 @@ paths:
                 $ref: '#/components/schemas/Error'
       tags:
       - comments
+  /api/events/:
+    get:
+      description: List events.
+      operationId: events_list
+      parameters:
+      - $ref: '#/components/parameters/Page'
+      - $ref: '#/components/parameters/PageSize'
+      - $ref: '#/components/parameters/Order'
+      - $ref: '#/components/parameters/Search'
+      - $ref: '#/components/parameters/BeforeFilter'
+      - $ref: '#/components/parameters/SinceFilter'
+      - in: query
+        name: project
+        schema:
+          description: ''
+          title: ''
+          type: string
+      - in: query
+        name: category
+        schema:
+          description: ''
+          title: ''
+          type: string
+          enum:
+            - cover-created
+            - patch-created
+            - patch-completed
+            - patch-state-changed
+            - patch-delegated
+            - check-created
+            - series-created
+            - series-completed
+      - in: query
+        name: series
+        schema:
+          description: ''
+          title: ''
+          type: string
+      - in: query
+        name: patch
+        schema:
+          description: ''
+          title: ''
+          type: string
+      - in: query
+        name: cover
+        schema:
+          description: ''
+          title: ''
+          type: string
+      responses:
+        '200':
+          description: ''
+          headers:
+            Link:
+              $ref: '#/components/headers/Link'
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  oneOf:
+                    - $ref: '#/components/schemas/EventCoverCreated'
+                    - $ref: '#/components/schemas/EventPatchCreated'
+                    - $ref: '#/components/schemas/EventPatchCompleted'
+                    - $ref: '#/components/schemas/EventPatchStateChanged'
+                    - $ref: '#/components/schemas/EventPatchDelegated'
+                    - $ref: '#/components/schemas/EventCheckCreated'
+                    - $ref: '#/components/schemas/EventSeriesCreated'
+                    - $ref: '#/components/schemas/EventSeriesCompleted'
+                  discriminator:
+                    propertyName: category
+                    mapping:
+                      cover-created: '#/components/schemas/EventCoverCreated'
+                      patch-created: '#/components/schemas/EventPatchCreated'
+                      patch-completed: '#/components/schemas/EventPatchCompleted'
+                      patch-state-changed: '#/components/schemas/EventPatchStateChanged'
+                      patch-delegated: '#/components/schemas/EventPatchDelegated'
+                      check-created: '#/components/schemas/EventCheckCreated'
+                      series-created: '#/components/schemas/EventSeriesCreated'
+                      series-completed: '#/components/schemas/EventSeriesCompleted'
+      tags:
+      - events
   /api/patches/:
     get:
       description: List patches.
@@ -1353,6 +1436,144 @@ components:
             type: string
             readOnly: true
             minLength: 1
+    EventBase:
+      type: object
+      properties:
+        id:
+          title: ID
+          type: integer
+          readOnly: true
+        category:
+          title: Category
+          description: The category of the event.
+          type: string
+          readOnly: true
+        project:
+          $ref: '#/components/schemas/ProjectEmbedded'
+        date:
+          title: Date
+          description: The time this event was created.
+          type: string
+          format: iso8601
+          readOnly: true
+        payload:
+          type: object
+    EventCoverCreated:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - cover-created
+          payload:
+            properties:
+              cover:
+                title: Cover
+                type: string
+                readOnly: true
+    EventPatchCreated:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - patch-created
+          payload:
+            properties:
+              patch:
+                $ref: '#/components/schemas/PatchEmbedded'
+    EventPatchCompleted:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - patch-completed
+          payload:
+            properties:
+              patch:
+                $ref: '#/components/schemas/PatchEmbedded'
+              series:
+                $ref: '#/components/schemas/SeriesEmbedded'
+    EventPatchStateChanged:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - patch-state-changed
+          payload:
+            properties:
+              patch:
+                $ref: '#/components/schemas/PatchEmbedded'
+              previous_state:
+                title: Previous state
+                type: string
+              current_state:
+                title: Current state
+                type: string
+    EventPatchDelegated:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - patch-delegated
+          payload:
+            properties:
+              patch:
+                $ref: '#/components/schemas/PatchEmbedded'
+              previous_delegate:
+                allOf:
+                - $ref: '#/components/schemas/UserEmbedded'
+                - title: Previous delegate
+              current_delegate:
+                allOf:
+                - $ref: '#/components/schemas/UserEmbedded'
+                - title: Current delegate
+    EventCheckCreated:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - check-created
+          payload:
+            properties:
+              patch:
+                $ref: '#/components/schemas/PatchEmbedded'
+              check:
+                $ref: '#/components/schemas/CheckEmbedded'
+    EventSeriesCreated:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - series-created
+          payload:
+            properties:
+              series:
+                $ref: '#/components/schemas/SeriesEmbedded'
+    EventSeriesCompleted:
+      allOf:
+      - $ref: '#/components/schemas/EventBase'
+      - type: object
+        properties:
+          category:
+            enum:
+              - series-completed
+          payload:
+            properties:
+              series:
+                $ref: '#/components/schemas/SeriesEmbedded'
     PatchList:
       required:
         - state
@@ -1711,6 +1932,50 @@ components:
           format: email
           readOnly: true
           minLength: 1
+    CheckEmbedded:
+      type: object
+      properties:
+        id:
+          title: ID
+          type: integer
+          readOnly: true
+        url:
+          title: Url
+          type: string
+          format: uri
+          readOnly: true
+        date:
+          title: Date
+          type: string
+          format: iso8601
+          readOnly: true
+        state:
+          title: State
+          description: The state of the check.
+          type: string
+          readOnly: true
+          enum:
+          - pending
+          - success
+          - warning
+          - fail
+        target_url:
+          title: Target url
+          description: The target URL to associate with this check. This should be specific
+            to the patch.
+          type: string
+          format: uri
+          maxLength: 200
+          nullable: true
+          readOnly: true
+        context:
+          title: Context
+          description: A label to discern check from checks of other testing systems.
+          type: string
+          pattern: ^[-a-zA-Z0-9_]+$
+          maxLength: 255
+          minLength: 1
+          readOnly: true
     CoverLetterEmbedded:
       type: object
       properties: