add descriptions

reference/alerts.v1.yaml

@@ -34,7 +34,7 @@ security:
 tags:
   - name: Alerts
     description: >-
-      Delete, Get, and Upsert alerts configurations.
+      Endpoints related to alert configuration and management.
 
 paths:
   /alerts/{userId}/{followedUserId}:
@@ -46,14 +46,16 @@ paths:
       summary: Delete an alerts configuration
       description: >-
         Delete an existing alerts configuration.
-      operationId: Delete
+      operationId: DeleteAlertsConfiguration
       responses:
         '200':
           $ref: '#/components/responses/OK'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
         '500':
@@ -65,14 +67,16 @@ paths:
       summary: Get an alerts configuration
       description: >-
         Retrieve an existing alerts configuration.
-      operationId: Get
+      operationId: GetAlertsConfiguration
       responses:
         '200':
           $ref: '#/components/responses/AlertsConfig'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
         '500':
@@ -86,7 +90,7 @@ paths:
         Create or update an alerts configuration.
 
         If no alerts configuration exists, it will be created.
-      operationId: Upsert
+      operationId: UpsertAlertsConfiguration
       requestBody:
         required: true
         content:
@@ -100,6 +104,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
         '500':
@@ -115,14 +121,17 @@ components:
 
   responses:
     OK:
-      description: "OK"
+      description: 'OK'
 
     BadRequest:
       description: 'Bad Request'
 
     Unauthorized:
       description: 'Unauthorized'
 
+    Forbidden:
+      description: 'Forbidden'
+
     NotFound:
       description: 'Not Found'
 
@@ -147,7 +156,7 @@ components:
 
     followedUserId:
       description: >-
-        Tidepool User ID of user who granted follow access
+        Tidepool User ID of the user who granted follow access.
       name: followedUserId
       in: path
       required: true
@@ -156,5 +165,4 @@ components:
 
   schemas:
     tidepoolUserId:
-      $ref: ./common/models/tidepooluserid.yaml
-
+      $ref: './common/models/tidepooluserid.yaml'

reference/common/models/alertdelay.v1.yaml

@@ -1,3 +1,5 @@
 type: integer
 minimum: 0
 maximum: 120
+description: >-
+  An amount of time, in minutes, to wait before alerting.

reference/common/models/alertrepeat.v1.yaml

@@ -2,4 +2,6 @@ type: integer
 minimum: 0
 maximum: 240
 description: >-
-  A value of 0 disables repeats.
+  An amount of time, in minutes, after which an alert will be repeated.
+
+  A value of 0 disables the repeat functionality.

reference/common/models/alertsconfig.v1.yaml

@@ -11,3 +11,6 @@ properties:
   notLooping:
     $ref: './notloopingalert.v1.yaml'
 minProperties: 1
+description: >-
+  Configuration for alerts triggered in response to the status of a user's
+  device and data.

reference/common/models/alertthreshold.v1.yaml

@@ -15,3 +15,5 @@ properties:
 required:
   - value
   - units
+description: >-
+  A blood glucose measurement value, above or below which an alert should be triggered.

reference/common/models/highalert.v1.yaml

@@ -5,6 +5,8 @@ properties:
   repeat:
     $ref: './alertrepeat.v1.yaml'
   threshold:
-    $ref: "./alertthreshold.v1.yaml"
+    $ref: './alertthreshold.v1.yaml'
   delay:
-    $ref: "./alertdelay.v1.yaml"
+    $ref: './alertdelay.v1.yaml'
+description: >-
+  Blood glucose measurements at or above this value will trigger an alert.

reference/common/models/lowalert.v1.yaml

@@ -5,6 +5,8 @@ properties:
   repeat:
     $ref: './alertrepeat.v1.yaml'
   threshold:
-    $ref: "./alertthreshold.v1.yaml"
+    $ref: './alertthreshold.v1.yaml'
   delay:
-    $ref: "./alertdelay.v1.yaml"
+    $ref: './alertdelay.v1.yaml'
+description: >-
+  Blood glucose measurements at or below this value will trigger an alert.

reference/common/models/nocommunicationalert.v1.yaml

@@ -5,4 +5,6 @@ properties:
   repeat:
     $ref: './alertrepeat.v1.yaml'
   delay:
-    $ref: "./alertdelay.v1.yaml"
+    $ref: './alertdelay.v1.yaml'
+description: >-
+  An alert sent when issues prevent the display of CGM data.

reference/common/models/notloopingalert.v1.yaml

@@ -5,4 +5,6 @@ properties:
   repeat:
     $ref: './alertrepeat.v1.yaml'
   delay:
-    $ref: "./alertdelay.v1.yaml"
+    $ref: './alertdelay.v1.yaml'
+description: >-
+  An alert sent when the Tidepool Loop app is unable to loop.

reference/common/models/urgentlowalert.v1.yaml

@@ -6,3 +6,5 @@ properties:
     $ref: './alertrepeat.v1.yaml'
   threshold:
     $ref: './alertthreshold.v1.yaml'
+description: >-
+  Blood glucose measurements at or below this value will trigger an immediate and urgent alert.