add documentation for /event path (#61)

openapi/event/methods.yml

@@ -0,0 +1,22 @@
+events:
+  delete:
+    summary: "Deletes all notification events"
+    operationId: DeleteEvents
+    tags:
+      - event
+    responses:
+      200:
+        description: "Events removed successfully."
+
+eventForTrigger:
+  get:
+    summary: "Gets all trigger events for current page and their count"
+    operationId: GetTriggerEvents
+    tags:
+      - event
+    parameters:
+      - $ref: ../shared/parameters/_index.yml#/triggerID
+      - $ref: ../shared/parameters/_index.yml#/page
+      - $ref: ../shared/parameters/_index.yml#/size
+    responses:
+      $ref: ./responses.yml#/getTriggerEvents

openapi/event/responses.yml

@@ -0,0 +1,27 @@
+getTriggerEvents:
+  200:
+    description: "Events fetched successfully."
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            page:
+              type: integer
+              description: "Current page being displayed. Pages are zero-indexed."
+              example: 0
+            size:
+              type: integer
+              description: "Maximum number of items displayed per page."
+              example: 100
+            total:
+              type: integer
+              description: "Total number of available events for the trigger"
+              example: 10
+            list:
+              type: array
+              description: "List of trigger events"
+              items:
+                $ref: "../shared/schemas/Event.yml#/Event"
+  400:
+    $ref: "../shared/responses/_index.yml#/BadRequest"

openapi/main.yml

@@ -10,6 +10,8 @@ tags:
     description: "View Moira's runtime configuration. For more details, see <https://moira.readthedocs.io/en/latest/installation/configuration.html/>"
   - name: "contact"
     description: "APIs for working with Moira contacts. For more details, see <https://moira.readthedocs.io/en/latest/installation/webhooks_scripts.html#contact/>"
+  - name: "event"
+    description: "APIs for interacting with notification events. see <https://moira.readthedocs.io/en/latest/user_guide/trigger_page.html#event-history/> for details"
 
 servers:
   - url: http://localhost:8080/api
@@ -23,6 +25,10 @@ paths:
     $ref: ./contact/methods.yml#/contact
   /contact/{contactId}/test:
     $ref: ./contact/methods.yml#/testContact
+  /event/all:
+    $ref: ./event/methods.yml#/events
+  /event/{triggerID}:
+    $ref: ./event/methods.yml#/eventForTrigger
 
 components:
   schemas:

openapi/shared/parameters/_index.yml

@@ -6,4 +6,32 @@ contactId:
     type: string
     format: uuid
   description: The ID of the target contact
-  example: "bcba82f5-48cf-44c0-b7d6-e1d32c64a88c"
+  example: "bcba82f5-48cf-44c0-b7d6-e1d32c64a88c"
+
+page:
+  in: query
+  name: page
+  required: false
+  schema:
+    type: integer
+  description: "Defines the number of the displayed page. E.g, page=2 would display the 2nd page."
+  example: 1
+
+size:
+  in: query
+  name: size
+  required: false
+  schema:
+    type: integer
+  description: "Number of items to be displayed on one page."
+  example: 15
+
+triggerID:
+  in: path
+  name: triggerID
+  required: true
+  schema:
+    type: string
+    format: uuid
+  description: The ID of updated trigger
+  example: 5A8AF369-86D2-44DD-B514-D47995ED6AF7

openapi/shared/schemas/Event.yml

@@ -0,0 +1,55 @@
+Event:
+  type: object
+  properties:
+    trigger_event:
+      type: boolean
+    timestamp:
+      type: integer
+      example: 1590741878
+    metric:
+      type: string
+      example: "carbon.agents.*.metricsReceived"
+    value:
+      type: number
+      example: 70
+    state:
+      type: string
+      description: "State of the metric after the data point was recorded."
+      enum: ["OK", "WARN", "ERROR", "NODATA", "EXCEPTION", "TEST"]
+      example: "OK"
+    trigger_id:
+      type: string
+      format: uuid
+      example: "5ff37996-8927-4cab-8987-970e80d8e0a8"
+    sub_id:
+      type: string
+    contactId:
+      type: string
+    old_state:
+      type: string
+      description: "State of the metric before the data point was recorded. Takes the same value as `state`."
+      example: "ERROR"
+    msg:
+      type: string
+    event_message:
+      "$ref": "#/definitions/EventInfo"
+
+definitions:
+  EventInfo:
+    type: object
+    properties:
+      maintenance:
+        "$ref": "#/definitions/MaintenanceInfo"
+      interval:
+        type: integer
+  MaintenanceInfo:
+    type: object
+    properties:
+      setup_user:
+        type: string
+      setup_time:
+        type: integer
+      remove_user:
+        type: string
+      remove_time:
+        type: integer

openapi/shared/schemas/_index.yml

@@ -1,4 +1,6 @@
 Contact:
   $ref: "./Contact.yml#/Contact"
 ContactRequest:
-  $ref: "./Contact.yml#/ContactRequest"
+  $ref: "./Contact.yml#/ContactRequest"
+Event:
+  $ref: "./Event.yml#/Event"