feat: Update swagger to openapi 3.0.4, update request payloads with examples (#11374)

2025-05-22 19:26:44 +12:00
parent 8697a30dc5
commit 4b417ce9e7
189 changed files with 10098 additions and 5847 deletions
--- a/swagger/paths/application/contacts/conversations.yml
+++ b/swagger/paths/application/contacts/conversations.yml
@@ -1,22 +1,43 @@
+parameters:
+  - $ref: '#/components/parameters/account_id'
+  - name: id
+    in: path
+    required: true
+    schema:
+      type: number
+    description: ID of the contact
+
 get:
  tags:
    - Contacts
  operationId: contactConversations
  summary: Contact Conversations
-  description: Get conversations associated to that contact
+  description: Get conversations associated with that contact
  parameters:
-    - $ref: '#/parameters/account_id'
    - name: id
      in: path
-      type: number
-      description: ID of the contact
      required: true
-  responses:
-    200:
-      description: Success
      schema:
-        $ref: '#/definitions/contact_conversations'
-    404:
+        type: number
+      description: ID of the contact
+  security:
+    - userApiKey: []
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_conversations'
+    '404':
      description: Contact not found
-    403:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '403':
      description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
--- a/swagger/paths/application/contacts/crud.yml
+++ b/swagger/paths/application/contacts/crud.yml
@@ -1,58 +1,94 @@
 parameters:
-  - $ref: '#/parameters/account_id'
+  - $ref: '#/components/parameters/account_id'
  - name: id
    in: path
-    type: number
-    description: ID of the contact
    required: true
+    schema:
+      type: number
+    description: ID of the contact

 get:
  tags:
    - Contacts
  operationId: contactDetails
  summary: Show Contact
+  security:
+    - userApiKey: []
  description: Get a contact belonging to the account using ID
  responses:
-    200:
+    '200':
      description: Success
-      schema:
-        $ref: '#/definitions/extended_contact'
-    404:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/extended_contact'
+    '404':
      description: Contact not found
-    403:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '403':
      description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

 put:
  tags:
    - Contacts
  operationId: contactUpdate
  summary: Update Contact
+  security:
+    - userApiKey: []
  description: Update a contact belonging to the account using ID
-  parameters:
-    - name: data
-      in: body
-      required: true
-      schema:
-        $ref: '#/definitions/contact_update'
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/contact_update_payload'
  responses:
-    204:
+    '204':
      description: Success
-      schema:
-        $ref: '#/definitions/contact_base'
-    404:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_base'
+    '404':
      description: Contact not found
-    403:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '403':
      description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

 delete:
  tags:
    - Contacts
  operationId: contactDelete
  summary: Delete Contact
+  security:
+    - userApiKey: []
+  description: Delete a contact belonging to the account using ID
  responses:
-    200:
+    '200':
      description: Success
-    401:
+    '401':
      description: Unauthorized
-    404:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '404':
      description: Contact not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
--- a/swagger/paths/application/contacts/filter.yml
+++ b/swagger/paths/application/contacts/filter.yml
@@ -1,58 +1,64 @@
-tags:
-  - Contacts
-operationId: contactFilter
-description: Filter contacts with custom filter options and pagination
-summary: Contact Filter
-security:
-  - userApiKey: []
-  - agentBotApiKey: []
-parameters:
-  - name: page
-    in: query
-    type: integer
-  - name: body
-    in: body
+post:
+  tags:
+    - Contacts
+  operationId: contactFilter
+  description: Filter contacts with custom filter options and pagination
+  summary: Contact Filter
+  security:
+    - userApiKey: []
+  parameters:
+    - $ref: '#/components/parameters/account_id'
+    - name: page
+      in: query
+      schema:
+        type: number
+  requestBody:
    required: true
-    schema:
-      type: object
-      properties:
-        payload:
-          type: array
-          items:
-            type: object
-            properties:
-              attribute_key:
-                type: string
-                description: filter attribute name
-              filter_operator:
-                type: string
-                description: filter operator name
-                enum: [ equal_to, not_equal_to, contains, does_not_contain ]
-              values:
-                type: array
-                items:
-                  type: string
-                description: array of the attribute values to filter
-              query_operator:
-                type: string
-                description: query operator name
-                enum: [ AND, OR ]
-          example:
-            - attribute_key: 'name'
-              filter_operator: 'equal_to'
-              values: ['en']
-              query_operator: 'AND'
-            - attribute_key: 'country_code'
-              filter_operator: 'equal_to'
-              values: ['us']
-              query_operator: null
-
-responses:
-  200:
-    description: Success
-    schema:
-      $ref: '#/definitions/contact_list'
-  400:
-    description: Bad Request Error
-    schema:
-      $ref: '#/definitions/bad_request_error'
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            payload:
+              type: array
+              items:
+                type: object
+                properties:
+                  attribute_key:
+                    type: string
+                    description: filter attribute name
+                  filter_operator:
+                    type: string
+                    description: filter operator name
+                    enum: [equal_to, not_equal_to, contains, does_not_contain]
+                  values:
+                    type: array
+                    items:
+                      type: string
+                    description: array of the attribute values to filter
+                  query_operator:
+                    type: string
+                    description: query operator name
+                    enum: [AND, OR]
+              example:
+                - attribute_key: 'name'
+                  filter_operator: 'equal_to'
+                  values: ['en']
+                  query_operator: 'AND'
+                - attribute_key: 'country_code'
+                  filter_operator: 'equal_to'
+                  values: ['us']
+                  query_operator: null
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_list'
+    '400':
+      description: Bad Request Error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
--- a/swagger/paths/application/contacts/labels.yml
+++ b/swagger/paths/application/contacts/labels.yml
@@ -0,0 +1,79 @@
+parameters:
+  - $ref: '#/components/parameters/account_id'
+  - name: id
+    in: path
+    required: true
+    schema:
+      type: number
+    description: ID of the contact
+
+get:
+  tags:
+    - Contacts
+  operationId: list-all-labels-of-a-contact
+  summary: List Labels
+  description: Lists all the labels of a contact
+  security:
+    - userApiKey: []
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_labels'
+    '401':
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '404':
+      description: Contact not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+
+post:
+  tags:
+    - Contacts
+  operationId: contact-add-labels
+  summary: Add Labels
+  description: Add labels to a contact. Note that this API would overwrite the existing list of labels associated to the conversation.
+  security:
+    - userApiKey: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          required:
+            - labels
+          properties:
+            labels:
+              type: array
+              description: Array of labels (comma-separated strings)
+              items:
+                type: string
+              example: ['support', 'billing']
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_labels'
+    '401':
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '404':
+      description: Contact not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
--- a/swagger/paths/application/contacts/labels/create.yml
+++ b/swagger/paths/application/contacts/labels/create.yml
@@ -1,26 +0,0 @@
-tags:
-  - Contact Labels
-operationId: contact-add-labels
-summary: Add Labels
-description: Add labels to a contact. Note that this API would overwrite the existing list of labels associated to the conversation.
-parameters:
-  - name: data
-    in: body
-    required: true
-    schema:
-      type: object
-      properties:
-        labels:
-          type: array
-          description: Array of labels (comma-separated strings)
-          items:
-            type: string
-responses:
-  200:
-    description: Success
-    schema:
-      $ref: '#/definitions/contact_labels'
-  404:
-    description: Contact not found
-  401:
-    description: Unauthorized
--- a/swagger/paths/application/contacts/labels/index.yml
+++ b/swagger/paths/application/contacts/labels/index.yml
@@ -1,14 +0,0 @@
-tags:
-  - Contact Labels
-operationId: list-all-labels-of-a-contact
-summary: List Labels
-description: Lists all the labels of a contact
-responses:
-  200:
-    description: Success
-    schema:
-      $ref: '#/definitions/contact_labels'
-  404:
-    description: Contact not found
-  401:
-    description: Unauthorized
--- a/swagger/paths/application/contacts/list_create.yml
+++ b/swagger/paths/application/contacts/list_create.yml
@@ -2,21 +2,27 @@ get:
  tags:
    - Contacts
  operationId: contactList
-  description: Listing all the resolved contacts with pagination (Page size = 15) . Resolved contacts are the ones with a value for identifier, email or phone number
+  description: Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
  summary: List Contacts
+  security:
+    - userApiKey: []
  parameters:
-    - $ref: '#/parameters/account_id'
-    - $ref: '#/parameters/contact_sort_param'
-    - $ref: '#/parameters/page'
+    - $ref: '#/components/parameters/account_id'
+    - $ref: '#/components/parameters/contact_sort_param'
+    - $ref: '#/components/parameters/page'
  responses:
-    200:
+    '200':
      description: Success
-      schema:
-        $ref: '#/definitions/contact_list'
-    400:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_list'
+    '400':
      description: Bad Request Error
-      schema:
-        $ref: '#/definitions/bad_request_error'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

 post:
  tags:
@@ -24,19 +30,26 @@ post:
  operationId: contactCreate
  description: Create a new Contact
  summary: Create Contact
+  security:
+    - userApiKey: []
  parameters:
-    - $ref: '#/parameters/account_id'
-    - name: data
-      in: body
-      required: true
-      schema:
-        $ref: '#/definitions/contact_create'
+    - $ref: '#/components/parameters/account_id'
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/contact_create_payload'
  responses:
-    200:
+    '200':
      description: Success
-      schema:
-        $ref: '#/definitions/extended_contact'
-    400:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/extended_contact'
+    '400':
      description: Bad Request Error
-      schema:
-        $ref: '#/definitions/bad_request_error'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
--- a/swagger/paths/application/contacts/search.yml
+++ b/swagger/paths/application/contacts/search.yml
@@ -4,23 +4,30 @@ get:
  operationId: contactSearch
  description: Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
  summary: Search Contacts
+  security:
+    - userApiKey: []
  parameters:
-    - $ref: '#/parameters/account_id'
+    - $ref: '#/components/parameters/account_id'
    - name: q
      in: query
-      type: string
+      schema:
+        type: string
      description: Search using contact `name`, `identifier`, `email` or `phone number`
-    - $ref: '#/parameters/contact_sort_param'
-    - $ref: '#/parameters/page'
+    - $ref: '#/components/parameters/contact_sort_param'
+    - $ref: '#/components/parameters/page'
  responses:
-    200:
+    '200':
      description: Success
-      schema:
-        type: object
-        properties:
-          payload:
-            $ref: '#/definitions/contact_list'
-    401:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              payload:
+                $ref: '#/components/schemas/contact_list'
+    '401':
      description: Authentication error
-      schema:
-        $ref: '#/definitions/bad_request_error'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'