Fix: Make swagger doc compliant to OpenAPI (#3394)

This fixes issues in the swagger.json file. The motivation to do so is to be able to generate API clients using https://openapi-generator.tech Doing so will require further changes to the api spec, but this seems like a good first step since it is now "valid" according to editor.swagger.io and openapi-generator validate.

Fixes #2806

.circleci/config.yml

@@ -7,7 +7,7 @@ defaults: &defaults
   working_directory: ~/build
   docker:
     # specify the version you desire here
-    - image: cimg/ruby:3.0.2-node
+    - image: cimg/ruby:3.0.2-browsers
 
     # Specify service dependencies here if necessary
     # CircleCI maintains a library of pre-built images
@@ -77,6 +77,18 @@ jobs:
           paths:
             - cc-test-reporter
 
+      # verify swagger specification
+      - run:
+          name: Verify swagger API specification
+          command: |
+            bundle exec rake swagger:build
+            if [[ `git status swagger/swagger.json --porcelain` ]]
+            then
+              echo "ERROR: The swagger.json file is not in sync with the yaml specification. Run 'rake swagger:build' and commit 'swagger/swagger.json'."
+              exit 1
+            fi
+            curl -L https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.3.0/openapi-generator-cli-5.3.0.jar > ~/tmp/openapi-generator-cli-5.3.0.jar
+            java -jar ~/tmp/openapi-generator-cli-5.3.0.jar validate -i swagger/swagger.json
       # Database setup
       - run: yarn install --check-files
       - run: bundle exec rake db:create

swagger/definitions/request/contact/create.yml

@@ -1,8 +1,9 @@
 type: object
+required:
+  - inbox_id
 properties:
   inbox_id:
     type: number
-    required: true
   name:
     type: string
     description: name of the contact
@@ -12,7 +13,7 @@ properties:
   phone_number:
     type: string
     description: phone number of the contact
-  identifier: 
+  identifier:
     type: string
     description: A unique identifier for the contact in external system
   custom_attributes:

swagger/definitions/request/conversation/create_message.yml

@@ -1,9 +1,10 @@
 type: object
+required:
+  - content
 properties:
   content:
     type: string
     description: The content of the message
-    required: true
   message_type:
     type: string
     enum: ['outgoing', 'incoming']
@@ -18,4 +19,3 @@ properties:
   content_attributes:
     type: object
     description: attributes based on your content type
-    

swagger/definitions/resource/conversation.yml

@@ -5,6 +5,8 @@ properties:
     description: ID of the conversation
   messages:
     type: array
+    items:
+      $ref: '#/definitions/message'
   account_id:
     type: number
     description: Account Id
@@ -21,7 +23,7 @@ properties:
   contact_last_seen_at:
     type: string
   agent_last_seen_at:
-    type: agent_last_seen_at
+    type: string
   unread_count:
     type: number
     description: The number of unread messages

swagger/definitions/resource/custom_filter.yml

@@ -14,8 +14,10 @@ properties:
     type: object
     description: A query that needs to be saved as a custom filter
   created_at:
-    type: datetime
+    type: string
+    format: date-time
     description: The time at which the custom filter was created
   updated_at:
-    type: datetime
+    type: string
+    format: date-time
     description: The time at which the custom filter was updated

swagger/definitions/resource/integrations/app.yml

@@ -20,4 +20,6 @@ properties:
     description: Whether multiple hooks can be created for the integration
   hooks:
     type: array
+    items:
+      type: object
     description: If there are any hooks created for this integration

swagger/definitions/resource/public/conversation.yml

@@ -1,5 +1,5 @@
 type: object
-properties: 
+properties:
   id:
     type: integer
     description: Id of the conversation
@@ -8,7 +8,9 @@ properties:
     description: The inbox id of the conversation
   messages:
     type: array
+    items:
+      $ref: '#/definitions/message'
     description: Messages in the conversation
   contact:
     type: object
-    description: The contact information associated to the conversation
+    description: The contact information associated to the conversation

swagger/definitions/resource/public/message.yml

@@ -1,5 +1,5 @@
 type: object
-properties: 
+properties:
   id:
     type: string
     description: Id of the message
@@ -23,6 +23,8 @@ properties:
     description: Conversation Id of the message
   attachments:
     type: array
+    items:
+      type: object
     description: Attachments if any
   sender:
     type: object

swagger/index.yml

@@ -10,7 +10,7 @@ info:
     name: MIT License
     url: https://opensource.org/licenses/MIT
 host: app.chatwoot.com
-basePath:
+basePath: /
 schemes:
   - https
 produces:

swagger/parameters/account_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: account_id
-schema:
+type: integer
-  type: integer
 required: true
 description: The numeric ID of the account

swagger/parameters/agent_bot_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: id
-schema:
+type: integer
-  type: integer
 required: true
 description: The ID of the agentbot to be updated

swagger/parameters/contact_sort.yml

@@ -1,15 +1,14 @@
 in: query
 name: sort
-schema:
+type: string
-  type: string
+enum:
-  enum:
+  - name
-    - name
+  - email
-    - email
+  - phone_number
-    - phone_number
+  - last_activity_at
-    - last_activity_at
+  - -name
-    - -name
+  - -email
-    - -email
+  - -phone_number
-    - -phone_number
+  - -last_activity_at
-    - -last_activity_at
 required: false
 description: The attribute by which list should be sorted

swagger/parameters/conversation_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: conversation_id
-schema:
+type: integer
-  type: integer
 required: true
 description: The numeric ID of the conversation

swagger/parameters/custom_filter_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: custom_filter_id
-schema:
+type: integer
-  type: integer
 required: true
 description: The numeric ID of the custom filter

swagger/parameters/hook_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: hook_id
-schema:
+type: integer
-  type: integer
 required: true
 description: The numeric ID of the integration hook

swagger/parameters/inbox_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: inbox_id
-schema:
+type: integer
-  type: integer
 required: true
 description: The ID of the Inbox

swagger/parameters/message_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: message_id
-schema:
+type: integer
-  type: integer
 required: true
 description: The numeric ID of the message

swagger/parameters/page.yml

@@ -1,7 +1,6 @@
 in: query
 name: page
-schema:
+type: integer
-  type: integer
+default: 1
-  default: 1
 required: false
 description: The page parameter

swagger/parameters/platform_user_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: id
-schema:
+type: integer
-  type: integer
 required: true
 description: The numeric ID of the user on the platform

swagger/parameters/public/contact_identifier.yml

@@ -1,6 +1,5 @@
 in: path
 name: contact_identifier
-schema:
+type: string
-  type: string
 required: true
 description: The source id of contact obtained on contact create

swagger/parameters/public/inbox_identifier.yml

@@ -1,6 +1,5 @@
 in: path
 name: inbox_identifier
-schema:
+type: string
-  type: string
 required: true
 description: The identifier obtained from API inbox channel

swagger/parameters/report_metric.yml

@@ -1,7 +1,12 @@
 in: query
 name: metric
-schema:
+type: string
-  type: string
+enum:
-  enum: [conversations_count, incoming_messages_count, outgoing_messages_count, avg_first_response_time, avg_resolution_time, resolutions_count]
+  - conversations_count
+  - incoming_messages_count
+  - outgoing_messages_count
+  - avg_first_response_time
+  - avg_resolution_time
+  - resolutions_count
 required: true
 description: The type of metric

swagger/parameters/report_type.yml

@@ -1,7 +1,11 @@
 in: query
 name: report_type
-schema:
+type: string
-  type: string
+enum:
-  enum: [account,agent,inbox,label,team]
+  - account
+  - agent
+  - inbox
+  - label
+  - team
 required: true
-description: Type of report 
+description: Type of report

swagger/parameters/source_id.yml

@@ -1,2 +1,5 @@
+in: path
+name: source_id
+required: true
 type: string
-description: "Id of the session for which the conversation is created.\n\n\n\n Source Ids can be obtained through contactable inboxes API or via generated.<br/><br/>Website: Chatwoot generated string which can be obtained from webhook events. <br/> Phone Channels(Twilio): Phone number in e164 format <br/> Email Channels: Contact Email address <br/> API Channel: Any Random String"
+description: "Id of the session for which the conversation is created.\n\n\n\n Source Ids can be obtained through contactable inboxes API or via generated.<br/><br/>Website: Chatwoot generated string which can be obtained from webhook events. <br/> Phone Channels(Twilio): Phone number in e164 format <br/> Email Channels: Contact Email address <br/> API Channel: Any Random String"

swagger/parameters/team_id.yml

@@ -1,6 +1,5 @@
 in: path
 name: id
-schema:
+type: integer
-  type: integer
 required: true
 description: The ID of the team to be updated

swagger/paths/application/agent_bots/index.yml

@@ -10,7 +10,7 @@ responses:
       type: array
       description: 'Array of agent bots'
       items:
-        - $ref: '#/definitions/agent_bot'
+        $ref: '#/definitions/agent_bot'
 
   401:
     description: Unauthorized

swagger/paths/application/agents/create.yml

@@ -11,21 +11,22 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - name
+        - email
+        - role
       properties:
-        name: 
+        name:
           type: string
           description: Full Name of the agent
-          required: true
         email:
           type: string
           description: Email of the Agent
-          required: true
+        role:
-        role: 
           type: string
           enum: ['agent', 'administrator']
           description: Whether its administrator or agent
-          required: true
+        availability_status:
-        availability_status: 
           type: string
           enum: ['available', 'busy', 'offline']
           description: The availability setting of the agent.

swagger/paths/application/agents/delete.yml

@@ -8,8 +8,7 @@ security:
 parameters:
   - in: path
     name: id
-    schema:
+    type: integer
-      type: integer
     required: true
     description: The ID of the agent to be deleted
 responses:

swagger/paths/application/agents/update.yml

@@ -8,8 +8,7 @@ security:
 parameters:
   - in: path
     name: id
-    schema:
+    type: integer
-      type: integer
     required: true
     description: The ID of the agent to be updated.
   - name: data
@@ -17,13 +16,14 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - role
       properties:
-        role: 
+        role:
           type: string
           enum: ['agent', 'administrator']
           description: Whether its administrator or agent
-          required: true
+        availability:
-        availability: 
           type: string
           enum: ['available', 'busy', 'offline']
           description: The availability setting of the agent.
@@ -39,4 +39,4 @@ responses:
   404:
     description: Agent not found
   403:
-    description: Access denied
+    description: Access denied

swagger/paths/application/contact_inboxes/create.yml

@@ -16,13 +16,15 @@ post:
       required: true
       schema:
         type: object
+        required:
+          - inbox_id
         properties:
           inbox_id:
             type: number
             description: The ID of the inbox
-            required: true
           source_id:
-            $ref: '#/parameters/source_id'
+            type: string
+            description: Contact Inbox Source Id
   responses:
     200:
       description: Success

swagger/paths/application/contacts/crud.yml

@@ -1,16 +1,17 @@
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: id
+    in: path
+    type: number
+    description: ID of the contact
+    required: true
+
 get:
   tags:
     - Contact
   operationId: contactDetails
   summary: Show Contact
   description: Get a contact belonging to the account using ID
-  parameters:
-    - $ref: '#/parameters/account_id'
-    - name: id
-      in: path
-      type: number
-      description: ID of the contact
-      required: true
   responses:
     200:
       description: Success
@@ -28,12 +29,6 @@ put:
   summary: Update Contact
   description: Update a contact belonging to the account using ID
   parameters:
-    - $ref: '#/parameters/account_id'
-    - name: id
-      in: path
-      type: number
-      description: ID of the contact
-      required: true
     - name: data
       in: body
       required: true
@@ -54,16 +49,10 @@ delete:
     - Contact
   operationId: contactDelete
   summary: Delete Contact
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the contact
-      required: true
   responses:
     200:
       description: Success
     401:
       description: Unauthorized
     404:
-      description: Contact not found
+      description: Contact not found

swagger/paths/application/conversation/create.yml

@@ -1,41 +0,0 @@
-get:
-  tags:
-    - Conversation
-  operationId: conversationList
-  description: List all the conversations with pagination
-  summary: Conversations List
-  parameters:
-    - $ref: '#/parameters/account_id'
-    - name: assignee_type
-      in: query
-      type: string
-      enum: ['me', 'unassigned', 'all', 'assigned']
-      required: true
-    - name: status
-      in: query
-      type: string
-      enum: ['open', 'resolved', 'pending']
-      required: true
-    - name: page
-      in: query
-      type: integer
-      required: true
-    - name: inbox_id
-      in: query
-      type: integer
-    - name: labels
-      in: query
-      type: array
-      items:
-        type: string
-
-  responses:
-    200:
-      description: Success
-      schema:
-        $ref: '#/definitions/conversation_list'
-    400:
-      description: Bad Request Error
-      schema:
-        $ref: '#/definitions/bad_request_error'
-    description: Access denied

swagger/paths/application/conversation/filter.yml

@@ -1,44 +1,43 @@
-post:
+tags:
-  tags:
+  - Conversation
-    - Conversation
+operationId: conversationFilter
-  operationId: conversationFilter
+description: Filter conversations with custom filter options and pagination
-  description: Filter conversations with custom filter options and pagination
+summary: Conversations Filter
-  summary: Conversations Filter
+security:
-  security:
+  - userApiKey: []
-    - userApiKey: []
+  - agentBotApiKey: []
-    - agentBotApiKey: []
+parameters:
-  parameters:
+  - name: page
-    - name: page
+    in: query
-      in: query
+    type: integer
-      type: integer
+  - name: payload
-    - name: payload
+    in: body
-      in: body
+    required: true
-      required: true
+    schema:
-      schema:
+      type: array
-        type: array
+      items:
-        items:
+        type: object
-          type: object
+        properties:
-          properties:
+          attribute_key:
-            attribute_key:
+            type: string
+            description: filter attribute name
+          filter_operator:
+            type: string
+            description: filter operator name
+          values:
+            type: array
+            items:
               type: string
-              description: filter attribute name
+            description: array of the attribute values to filter
-            filter_operator:
+          query_operator:
-              type: string
+            type: string
-              description: filter operator name
+            description: query operator name
-            values:
+responses:
-              type: array
+  200:
-              description: array of the attribute values to filter
+    description: Success
-            query_operator:
+    schema:
-              type: string
+      $ref: '#/definitions/conversation_list'
-              description: query operator name
+  400:
-    - $ref: '#/parameters/account_id'
+    description: Bad Request Error
-  responses:
+    schema:
-    200:
+      $ref: '#/definitions/bad_request_error'
-      description: Success
-      schema:
-        $ref: '#/definitions/conversation_list'
-    400:
-      description: Bad Request Error
-      schema:
-        $ref: '#/definitions/bad_request_error'
-    description: Access denied

swagger/paths/application/conversation/index.yml

@@ -1,24 +1,27 @@
+parameters:
+  - $ref: '#/parameters/account_id'
+
 get:
   tags:
     - Conversation
-  operationId: conversationSearch
+  operationId: conversationList
-  description: Search for conversations containing a messages with the query string
+  description: List all the conversations with pagination
-  summary: Conversations Search
+  summary: Conversations List
   parameters:
-    - name: q
-      in: query
-      type: string
     - name: assignee_type
       in: query
       type: string
       enum: ['me', 'unassigned', 'all', 'assigned']
+      required: true
     - name: status
       in: query
       type: string
-      enum: ['open', 'resolved', 'pending', 'all']
+      enum: ['open', 'resolved', 'pending']
+      required: true
     - name: page
       in: query
       type: integer
+      required: true
     - name: inbox_id
       in: query
       type: integer
@@ -27,7 +30,6 @@ get:
       type: array
       items:
         type: string
-    - $ref: '#/parameters/account_id'
 
   responses:
     200:
@@ -38,8 +40,6 @@ get:
       description: Bad Request Error
       schema:
         $ref: '#/definitions/bad_request_error'
-    description: Access denied
-
 
 post:
   tags:
@@ -51,7 +51,6 @@ post:
     - userApiKey: []
     - agentBotApiKey: []
   parameters:
-    - $ref: '#/parameters/account_id'
     - name: data
       in: body
       required: true
@@ -59,7 +58,8 @@ post:
         type: object
         properties:
           source_id:
-            $ref: '#/parameters/source_id'
+            type: string
+            description: Conversation source id
           inbox_id:
             type: string
             description: "Id of inbox in which the conversation is created <br/> Allowed Inbox Types: Website, Phone, Api, Email "

swagger/paths/application/conversation/labels/create.yml

@@ -13,7 +13,7 @@ parameters:
         labels:
           type: array
           description: Array of labels (comma-separated strings)
-          properties:
+          items:
             type: string
 responses:
   200:

swagger/paths/application/conversation/messages/create_attachment.yml

@@ -31,7 +31,8 @@ post:
       type: array
       description: The files to be uploaded.
       items:
-        type: file
+        type: string
+        format: binary
 
 
   responses:

swagger/paths/application/conversation/messages/index.yml

@@ -6,12 +6,13 @@ description: List all messages of a conversation
 responses:
   200:
     description: Success
-    type: array
-    description: Array of messages
     schema:
-      allOf:
+      type: array
-        - $ref: '#/definitions/generic_id'
+      description: Array of messages
-        - $ref: '#/definitions/message'
+      items:
+        allOf:
+          - $ref: '#/definitions/generic_id'
+          - $ref: '#/definitions/message'
   404:
     description: Conversation not found
   401:

swagger/paths/application/conversation/toggle_status.yml

@@ -12,11 +12,12 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - status
       properties:
         status:
           type: string
           enum: ["open", "resolved", "pending"]
-          required: true
           description: The status of the conversation
 responses:
   200:

swagger/paths/application/inboxes/create.yml

@@ -16,7 +16,8 @@ post:
             type: string
             description: The name of the inbox
           avatar:
-            type: file
+            type: string
+            format: binary
             description: File for avatar image
           channel:
             type: object

swagger/paths/application/inboxes/inbox_members/create.yml

@@ -11,15 +11,18 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+          - inbox_id
+          - user_ids
       properties:
         inbox_id:
           type: string
           description: The ID of the inbox
-          required: true
+        user_ids:
-        user_ids: 
           type: array
+          items:
+            type: integer
           description: IDs of users to be added to the inbox
-          required: true
 responses:
   200:
     description: Success

swagger/paths/application/inboxes/inbox_members/delete.yml

@@ -11,15 +11,18 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - inbox_id
+        - user_ids
       properties:
         inbox_id:
           type: string
           description: The ID of the inbox
-          required: true
+        user_ids:
-        user_ids: 
           type: array
+          items:
+            type: integer
           description: IDs of users to be deleted from the inbox
-          required: true
 responses:
   200:
     description: Success

swagger/paths/application/inboxes/inbox_members/update.yml

@@ -2,7 +2,7 @@ tags:
   - Inbox
 operationId: update-agents-in-inbox
 summary: Update Agents in Inbox
-description: All agents execept the one passed in params will be removed
+description: All agents except the one passed in params will be removed
 security:
   - userApiKey: []
 parameters:
@@ -11,15 +11,18 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - inbox_id
+        - user_ids
       properties:
         inbox_id:
           type: string
           description: The ID of the inbox
-          required: true
+        user_ids:
-        user_ids: 
           type: array
+          items:
+            type: integer
           description: IDs of users to be added to the inbox
-          required: true
 responses:
   200:
     description: Success

swagger/paths/application/inboxes/set_agent_bot.yml

@@ -16,10 +16,11 @@ post:
       required: true
       schema:
         type: object
+        required:
+          - agent_bot
         properties:
           agent_bot:
             type: number
-            required: true
             description: 'Agent bot ID'
   responses:
     204:

swagger/paths/application/inboxes/update.yml

@@ -16,17 +16,18 @@ patch:
       required: true
       schema:
         type: object
+        required:
+          - enable_auto_assignment
         properties:
           name:
             type: string
             description: The name of the inbox
           enable_auto_assignment:
             type: boolean
-            required: true
             description: 'Enable Auto Assignment'
           avatar:
-            type: file
+            type: string
-            required: false
+            format: binary
             description: 'Image file for avatar'
           channel:
             type: object

swagger/paths/index.yml

@@ -2,10 +2,10 @@
 
 # Accounts
 
-platform/api/v1/accounts:
+/platform/api/v1/accounts:
   post:
     $ref: ./platform/accounts/create.yml
-platform/api/v1/accounts/{id}:
+/platform/api/v1/accounts/{account_id}:
   parameters:
     - $ref: '#/parameters/account_id'
   get:
@@ -18,7 +18,7 @@ platform/api/v1/accounts/{id}:
 
 # Account Users
 
-platform/api/v1/accounts/{id}/account_users:
+/platform/api/v1/accounts/{account_id}/account_users:
   parameters:
     - $ref: '#/parameters/account_id'
   get:
@@ -30,12 +30,12 @@ platform/api/v1/accounts/{id}/account_users:
 
 # AgentBots
 
-platform/api/v1/agent_bots:
+/platform/api/v1/agent_bots:
   get:
     $ref: ./platform/agent_bots/index.yml
   post:
     $ref: ./platform/agent_bots/create.yml
-platform/api/v1/agent_bots/{id}:
+/platform/api/v1/agent_bots/{id}:
   parameters:
     - $ref: '#/parameters/agent_bot_id'
   get:
@@ -47,10 +47,10 @@ platform/api/v1/agent_bots/{id}:
 
 # Users
 
-platform/api/v1/users:
+/platform/api/v1/users:
   post:
     $ref: ./platform/users/create.yml
-platform/api/v1/users/{id}:
+/platform/api/v1/users/{id}:
   parameters:
     - $ref: '#/parameters/platform_user_id'
   get:
@@ -59,10 +59,11 @@ platform/api/v1/users/{id}:
     $ref: ./platform/users/update.yml
   delete:
     $ref: ./platform/users/delete.yml
-platform/api/v1/users/{id}/login:
+/platform/api/v1/users/{id}/login:
   parameters:
     - $ref: '#/parameters/platform_user_id'
-  $ref: './platform/users/login.yml'
+  get:
+    $ref: './platform/users/login.yml'
 
 
 # ---------------- end of platform path -----------#
@@ -71,12 +72,12 @@ platform/api/v1/users/{id}/login:
 
 # Contacts
 
-public/api/v1/inboxes/{inbox_identifier}/contacts:
+/public/api/v1/inboxes/{inbox_identifier}/contacts:
   parameters:
     - $ref: '#/parameters/public_inbox_identifier'
   post:
     $ref: ./public/inboxes/contacts/create.yml
-public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}:
+/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}:
   parameters:
     - $ref: '#/parameters/public_inbox_identifier'
     - $ref: '#/parameters/public_contact_identifier'
@@ -86,7 +87,7 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}:
     $ref: ./public/inboxes/contacts/update.yml
 
 
-public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations:
+/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations:
   parameters:
     - $ref: '#/parameters/public_inbox_identifier'
     - $ref: '#/parameters/public_contact_identifier'
@@ -95,7 +96,7 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
   get:
     $ref: ./public/inboxes/conversations/index.yml
 
-public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages:
+/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages:
   parameters:
     - $ref: '#/parameters/public_inbox_identifier'
     - $ref: '#/parameters/public_contact_identifier'
@@ -104,7 +105,7 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
     $ref: ./public/inboxes/messages/create.yml
   get:
     $ref: ./public/inboxes/messages/index.yml
-public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages/{message_id}:
+/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages/{message_id}:
   parameters:
     - $ref: '#/parameters/public_inbox_identifier'
     - $ref: '#/parameters/public_contact_identifier'
@@ -139,11 +140,15 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
 
 # Agents
 /api/v1/accounts/{account_id}/agents:
+  parameters:
+    - $ref: '#/parameters/account_id'
   get:
     $ref: ./application/agents/index.yml
   post:
     $ref: ./application/agents/create.yml
 /api/v1/accounts/{account_id}/agents/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
   patch:
     $ref: ./application/agents/update.yml
   delete:
@@ -167,18 +172,13 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
 
 # Conversations
 /api/v1/accounts/{account_id}/conversations:
-  parameters:
-    - $ref: '#/parameters/account_id'
   $ref: ./application/conversation/index.yml
-/api/v1/accounts/{account_id}/conversations/:
-  parameters:
-    - $ref: '#/parameters/account_id'
-  $ref: ./application/conversation/create.yml
 /api/v1/accounts/{account_id}/conversations/filter:
   parameters:
     - $ref: '#/parameters/account_id'
-  $ref: ./application/conversation/filter.yml
+  post:
-/api/v1/accounts/{account_id}/conversations/{converstion_id}:
+    $ref: ./application/conversation/filter.yml
+/api/v1/accounts/{account_id}/conversations/{conversation_id}:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
@@ -227,7 +227,10 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
   $ref: ./application/inboxes/set_agent_bot.yml
 
 # Inbox Members
-/api/v1/accounts/{account_id}/inbox_members:
+/api/v1/accounts/{account_id}/inbox_members/{inbox_id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/inbox_id'
   get:
     $ref: ./application/inboxes/inbox_members/show.yml
   post:
@@ -240,9 +243,7 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
 
 
 # Messages
-/api/v1/accounts/{account_id}/conversations/{id}/messages:
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages:
-  $ref: ./application/conversation/messages/create_attachment.yml
-/api/v1/accounts/{account_id}/conversations/{converstion_id}/messages:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
@@ -269,6 +270,7 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
 /api/v1/accounts/{account_id}/integrations/hooks:
   post:
     $ref: './application/integrations/hooks/create.yml'
+/api/v1/accounts/{account_id}/integrations/hooks/{hook_id}:
   patch:
     $ref: ./application/integrations/hooks/update.yml
   delete:
@@ -308,9 +310,8 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
     - $ref: '#/parameters/account_id'
     - in: query
       name: filter_type
-      schema:
+      type: string
-        type: string
+      enum: ['conversation', 'contact', 'report']
-        enum: ['conversation', 'contact', 'report']
       required: false
       description: The type of custom filter
   get:
@@ -331,48 +332,42 @@ public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversat
 ### Reports
 
 # List
-/api/v2/accounts/{id}/reports:
+/api/v2/accounts/{account_id}/reports:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/report_metric'
     - $ref: '#/parameters/report_type'
     - in: query
       name: id
-      schema:
+      type: string
-        type: string
       description: The Id of specific object in case of agent/inbox/label
     - in: query
       name: since
-      schema:
+      type: string
-        type: string
       description: The timestamp from where report should start.
     - in: query
       name: until
-      schema:
+      type: string
-        type: string
       description: The timestamp from where report should stop.
   get:
     $ref: './application/reports/index.yml'
 
 # Summary
-/api/v2/accounts/{id}/reports/summary:
+/api/v2/accounts/{account_id}/reports/summary:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/report_type'
     - in: query
       name: id
-      schema:
+      type: string
-        type: string
       description: The Id of specific object in case of agent/inbox/label
     - in: query
       name: since
-      schema:
+      type: string
-        type: string
       description: The timestamp from where report should start.
     - in: query
       name: until
-      schema:
+      type: string
-        type: string
       description: The timestamp from where report should stop.
   get:
     $ref: './application/reports/summary.yml'

swagger/paths/platform/account_users/create.yml

@@ -11,15 +11,16 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - user_id
+        - role
       properties: 
         user_id:
           type: integer
           description: The ID of the user
-          required: true
         role:
           type: string
           description: whether user is an administrator or agent
-          required: true
       
 responses:
   200:

swagger/paths/platform/account_users/delete.yml

@@ -11,11 +11,12 @@ parameters:
     required: true
     schema:
       type: object
+      required:
+        - user_id
       properties: 
         user_id:
           type: integer
           description: The ID of the user
-          required: true
 
 responses:
   200:

swagger/paths/platform/users/login.yml

@@ -1,21 +1,20 @@
-get:
+tags:
-  tags:
+  - Users
-    - Users
+operationId: get-sso-url-of-a-user
-  operationId: get-sso-url-of-a-user
+summary: Get User SSO Link
-  summary: Get User SSO Link
+description: Get the sso link of a user
-  description: Get the sso link of a user
+security:
-  security:
+  - platformAppApiKey: []
-    - platformAppApiKey: []
+responses:
-  responses:
+  200:
-    200:
+    description: Success
-      description: Success
+    schema:
-      schema:
+      type: object
-        type: object
+      properties:
-        properties:
+        url:
-          url:
+          type: string
-            type: string
+          description: SSO url to autenticate the user
-            description: SSO url to autenticate the user
+  401:
-    401:
+    description: Unauthorized
-      description: Unauthorized
+  404:
-    404:
+    description: The given user does not exist
-      description: The given user does not exist

swagger/paths/public/inboxes/contacts/create.yml

@@ -3,8 +3,7 @@ tags:
 operationId: create-a-contact
 summary: Create a contact
 description: Create a contact
-security:
+security: []
-  - nil
 parameters:
   - name: data
     in: body

swagger/paths/public/inboxes/contacts/show.yml

@@ -3,8 +3,7 @@ tags:
 operationId: get-details-of-a-contact
 summary: Get a contact
 description: Get the details of a contact
-security:
+security: []
-  - nil
 responses:
   200:
     description: Success

swagger/paths/public/inboxes/contacts/update.yml

@@ -3,8 +3,7 @@ tags:
 operationId: update-a-contact
 summary: Update a contact
 description: Update a contact's attributes
-security:
+security: []
-  - nil
 parameters:
   - name: data
     in: body

swagger/paths/public/inboxes/conversations/create.yml

@@ -3,8 +3,7 @@ tags:
 operationId: create-a-conversation
 summary: Create a conversation
 description: Create a conversation
-security:
+security: []
-  - nil
 responses:
   200:
     description: Success

swagger/paths/public/inboxes/messages/create.yml

@@ -3,8 +3,7 @@ tags:
 operationId: create-a-message
 summary: Create a message
 description: Create a message
-security:
+security: []
-  - nil
 parameters:
   - name: data
     in: body

swagger/paths/public/inboxes/messages/update.yml

@@ -3,8 +3,7 @@ tags:
 operationId: update-a-message
 summary: Update a message
 description: Update a message
-security:
+security: []
-  - nil
 parameters:
   - name: data
     in: body