Add Code Snippets to Spec Files (#677)

Author: DX-Bandwidth

site/specs/global.yml

@@ -531,7 +531,7 @@ info:
     |`NO_VALID_DID_FOUND`|`316`|The system could not find any valid did id in
     the request.|
 
-    |`CLI_PRIVACY_ACCOUNT_NOT_TRUSTED`|`317`|Your account is not authorised to
+    |`CLI_PRIVACY_ACCOUNT_NOT_TRUSTED`|`317`|Your account is not authorized to
     use this option.|
 
     |`CLI_PRIVACY_NOT_SUPPORTED`|`318`|Some dids do not support the cli privacy

site/specs/messaging.yml

@@ -1074,7 +1074,7 @@ paths:
         '202':
           $ref: '#/components/responses/createMessageResponse'
         '400':
-          $ref: '#/components/responses/messagingBadRequestError'
+          $ref: '#/components/responses/createMessageBadRequestError'
         '401':
           $ref: '#/components/responses/messagingUnauthorizedError'
         '403':
@@ -1432,7 +1432,7 @@ components:
       required: false
       description: The direction of the message. One of INBOUND OUTBOUND.
       schema:
-        $ref: '#/components/schemas/messageDirectionEnum'
+        $ref: '#/components/schemas/listMessageDirectionEnum'
     carrierName:
       in: query
       name: carrierName
@@ -1512,9 +1512,9 @@ components:
       type: string
       description: The priority specified by the user.
       enum:
-        - DEFAULT
-        - HIGH
-      example: DEFAULT
+        - default
+        - high
+      example: default
     messageStatusEnum:
       type: string
       description: >-
@@ -1549,6 +1549,19 @@ components:
         - sms
         - mms
       example: sms
+    fieldError:
+      type: object
+      properties:
+        fieldName:
+          type: string
+          description: The name of the field that contains the error
+          example: from
+        description:
+          type: string
+          description: The error associated with the field
+          example: >-
+            '+invalid' must be replaced with a valid E164 formatted telephone
+            number
     messagesList:
       title: MessagesList
       type: object
@@ -1610,6 +1623,7 @@ components:
         messageSize:
           type: integer
           description: The size of the message including message content and headers.
+          nullable: true
           example: 27
         messageLength:
           type: integer
@@ -1618,14 +1632,17 @@ components:
         attachmentCount:
           type: integer
           description: The number of attachments the message has.
+          nullable: true
           example: 1
         recipientCount:
           type: integer
           description: The number of recipients the message has.
+          nullable: true
           example: 1
         campaignClass:
           type: string
           description: The campaign class of the message if it has one.
+          nullable: true
           example: T
     pageInfo:
       title: PageInfo
@@ -1660,6 +1677,21 @@ components:
       required:
         - type
         - description
+    createMessageRequestError:
+      title: CreateMessageRequestError
+      type: object
+      properties:
+        type:
+          type: string
+        description:
+          type: string
+        fieldErrors:
+          type: array
+          items:
+            $ref: '#/components/schemas/fieldError'
+      required:
+        - type
+        - description
     media:
       title: Media
       type: object
@@ -1862,6 +1894,12 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/messagingRequestError'
+    createMessageBadRequestError:
+      description: Bad Request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/createMessageRequestError'
     messagingUnauthorizedError:
       description: Unauthorized
       content:

site/specs/phone-number-lookup.yml

@@ -480,8 +480,9 @@ components:
       properties:
         requestId:
           type: string
+          description: The phone number lookup request ID from Bandwidth.
         status:
-          type: string
+          $ref: '#/components/schemas/lookupStatusEnum'
     lookupStatus:
       type: object
       description: >-
@@ -501,51 +502,54 @@ components:
           type: array
           description: The carrier information results for the specified telephone number.
           items:
-            type: object
-            properties:
-              Response Code:
-                type: integer
-                description: Our vendor's response code.
-                example: 0
-              Message:
-                type: string
-                description: Message associated with the response code.
-                example: NOERROR
-              E.164 Format:
-                type: string
-                description: The telephone number in E.164 format.
-                example: '+19195551234'
-              Formatted:
-                type: string
-                description: The formatted version of the telephone number.
-                example: (919) 555-1234
-              Country:
-                type: string
-                description: The country of the telephone number.
-                example: US
-              Line Type:
-                type: string
-                description: The line type of the telephone number.
-                example: Mobile
-              Line Provider:
-                type: string
-                description: The messaging service provider of the telephone number.
-                example: Verizon Wireless
-              Mobile Country Code:
-                type: string
-                description: The first half of the Home Network Identity (HNI).
-                example: '310'
-              Mobile Network Code:
-                type: string
-                description: The second half of the HNI.
-                example: '010'
+            $ref: '#/components/schemas/lookupResult'
         failedTelephoneNumbers:
           type: array
           description: The telephone numbers whose lookup failed.
           items:
             type: string
           example:
             - '+191955512345'
+    lookupResult:
+      type: object
+      description: Carrier information results for the specified telephone number.
+      properties:
+        Response Code:
+          type: integer
+          description: Our vendor's response code.
+          example: 0
+        Message:
+          type: string
+          description: Message associated with the response code.
+          example: NOERROR
+        E.164 Format:
+          type: string
+          description: The telephone number in E.164 format.
+          example: '+19195551234'
+        Formatted:
+          type: string
+          description: The formatted version of the telephone number.
+          example: (919) 555-1234
+        Country:
+          type: string
+          description: The country of the telephone number.
+          example: US
+        Line Type:
+          type: string
+          description: The line type of the telephone number.
+          example: Mobile
+        Line Provider:
+          type: string
+          description: The messaging service provider of the telephone number.
+          example: Verizon Wireless
+        Mobile Country Code:
+          type: string
+          description: The first half of the Home Network Identity (HNI).
+          example: '310'
+        Mobile Network Code:
+          type: string
+          description: The second half of the HNI.
+          example: '010'
     tnLookupRequestError:
       type: object
       properties:
@@ -658,19 +662,20 @@ components:
   parameters:
     accountId:
       name: accountId
-      description: The ID of the Bandwidth account that the user belongs to.
       in: path
       required: true
       schema:
         type: string
-        example: '9900000'
+      description: The ID of the Bandwidth account that the user belongs to.
+      example: '9900000'
     requestId:
       name: requestId
       in: path
       required: true
       schema:
         type: string
-        example: 004223a0-8b17-41b1-bf81-20732adf5590
+      description: The phone number lookup request ID from Bandwidth.
+      example: 004223a0-8b17-41b1-bf81-20732adf5590
   examples:
     singleNumberRequestExample:
       summary: Example Number Lookup Request for One Number

site/specs/voice.yml

@@ -572,6 +572,8 @@ paths:
           $ref: '#/components/responses/voiceNotFoundError'
         '405':
           $ref: '#/components/responses/voiceNotAllowedError'
+        '409':
+          $ref: '#/components/responses/voiceConflictError'
         '415':
           $ref: '#/components/responses/voiceUnsupportedMediaTypeError'
         '429':
@@ -826,6 +828,8 @@ paths:
           $ref: '#/components/responses/voiceNotFoundError'
         '405':
           $ref: '#/components/responses/voiceNotAllowedError'
+        '409':
+          $ref: '#/components/responses/voiceConflictError'
         '415':
           $ref: '#/components/responses/voiceUnsupportedMediaTypeError'
         '429':
@@ -2472,7 +2476,7 @@ paths:
         - $ref: '#/components/parameters/recordingId'
       responses:
         '200':
-          $ref: '#/components/responses/downloadCallRecordingResponse'
+          $ref: '#/components/responses/downloadRecordingMediaResponse'
         '400':
           $ref: '#/components/responses/voiceBadRequestError'
         '401':
@@ -3778,7 +3782,7 @@ paths:
         - $ref: '#/components/parameters/recordingId'
       responses:
         '200':
-          $ref: '#/components/responses/downloadCallRecordingResponse'
+          $ref: '#/components/responses/downloadRecordingMediaResponse'
         '400':
           $ref: '#/components/responses/voiceBadRequestError'
         '401':
@@ -7311,7 +7315,7 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/callRecordingMetadata'
-    downloadCallRecordingResponse:
+    downloadRecordingMediaResponse:
       description: Media found
       content:
         audio/vnd.wave:
@@ -7410,6 +7414,15 @@ components:
           examples:
             notAllowedErrorExample:
               $ref: '#/components/examples/voiceNotAllowedErrorExample'
+    voiceConflictError:
+      description: Conflict
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/voiceApiError'
+          examples:
+            conflictErrorExample:
+              $ref: '#/components/examples/voiceConflictErrorExample'
     voiceUnsupportedMediaTypeError:
       description: Unsupported Media Type
       content:
@@ -7502,6 +7515,11 @@ components:
       value:
         type: validation
         description: 'Invalid answerUrl: only http and https are allowed'
+    voiceConflictErrorExample:
+      summary: Example of a Conflict (409) Error
+      value:
+        type: validation
+        description: 'Invalid answerUrl: only http and https are allowed'
     voiceUnsupportedMediaTypeErrorExample:
       summary: Example of an Unsupported Media Type (415) Error
       value: