chore: Add Swagger docs for Platform APIs (#2349)

swagger/definitions/index.yml

@@ -25,6 +25,8 @@ contactable_inboxes:
   $ref: ./resource/contactable_inboxes.yml
 account:
   $ref: ./resource/account.yml
+platform_account:
+  $ref: ./resource/platform_account.yml
 team:
   $ref: ./resource/team.yml
 integrations_app:
@@ -78,6 +80,15 @@ extended_message:
 
 # REQUEST
 
+account_create_update_payload:
+  $ref: ./request/account/create_update_payload.yml
+
+agent_bot_create_update_payload:
+  $ref: ./request/agent_bot/create_update_payload.yml
+
+user_create_update_payload:
+  $ref: ./request/account/create_update_payload.yml
+
 ## contact
 contact_create:
   $ref: ./request/contact/create.yml

swagger/definitions/request/account/create_update_payload.yml

@@ -0,0 +1,5 @@
+type: object
+properties:
+  name:
+    type: string
+    description: Name of the account

swagger/definitions/request/agent_bot/create_update_payload.yml

@@ -0,0 +1,11 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the agent bot
+  description:
+    type: string
+    description: The description about the agent bot
+  outgoing_url:
+    type: string
+    description: The webhook URL for the bot

swagger/definitions/request/user/create_update_payload.yml

@@ -0,0 +1,12 @@
+type: object
+properties:
+  name:
+    type: string
+    description: Name of the user
+  email:
+    type: string
+    description: Email of the user
+  password:
+    type: string
+    description: Password must contain uppercase, lowercase letters, number and a special character
+

swagger/definitions/resource/agent_bot.yml

@@ -3,12 +3,15 @@ properties:
   id:
     type: number
     description: ID of the agent bot
-  description:
-    type: string
-    description: The description about the agent bot
   name:
     type: string
     description: The name of the agent bot
+  description:
+    type: string
+    description: The description about the agent bot
+  account_id:
+    type: number
+    description: Account ID if it's an account specific bot
   outgoing_url:
     type: string
     description: The webhook URL for the bot

swagger/definitions/resource/platform_account.yml

@@ -0,0 +1,9 @@
+type: object
+properties:
+  id:
+    type: number
+    description: Account ID
+  name:
+    type: string
+    description: Name of the account
+

swagger/index.yml

@@ -5,12 +5,12 @@ info:
   title: Chatwoot
   termsOfService:	https://www.chatwoot.com/terms-of-service/
   contact:
-    email: support@chatwoot.com
+    email: hello@chatwoot.com
   license:
     name: MIT License
     url: https://opensource.org/licenses/MIT
 host: app.chatwoot.com
-basePath: /api/v1/
+basePath: 
 schemes:
   - https
 produces:
@@ -28,11 +28,11 @@ securityDefinitions:
     in: header
     name: api_access_token
     description: This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis.
-  superAdminApiKey:
+  platformAppApiKey:
     type: apiKey
     in: header
     name: api_access_token
-    description: This token is only for the system admin or obtained via rails console. This token is to be used rarely for cases like creating a pre verified user through api from external system.
+    description: This token can be obtained by the system admin after creating a platformApp. This token should be used to provision agent bots, accounts, users and their roles.
 security:
   - userApiKey: []
 
@@ -42,3 +42,23 @@ definitions:
   $ref: ./definitions/index.yml
 parameters:
   $ref: ./parameters/index.yml
+
+x-tagGroups:
+  - name: Platform
+    tags:
+      - Accounts
+      - Account Users
+      - AgentBots
+      - Users
+  - name: Application
+    tags:
+      - Account AgentBots
+      - Contact
+      - Conversation
+      - Conversation Assignment
+      - Conversation Labels
+      - Inbox
+      - Messages
+      - Integrations
+      - Profile
+      - Teams

swagger/parameters/agent_bot_id.yml

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

swagger/parameters/index.yml

@@ -1,6 +1,9 @@
 account_id:
   $ref: ./account_id.yml
 
+agent_bot_id:
+  $ref: ./agent_bot_id.yml
+
 team_id:
   $ref: ./team_id.yml
 

swagger/paths/agent_bots/create.yml

@@ -0,0 +1,19 @@
+tags:
+  - Account AgentBots
+operationId: create-an-account-agent-bot
+summary: Create an Agent Bot
+description: Create an agent bot in the account
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized

swagger/paths/agent_bots/delete.yml

@@ -0,0 +1,12 @@
+tags:
+  - Account AgentBots
+operationId: delete-an-account-agent-bot
+summary: Delete an AgentBot
+description: Delete an AgentBot from the account
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The agent bot does not exist in the account

swagger/paths/agent_bots/index.yml

@@ -1,17 +1,16 @@
-get:
-  tags:
-    - AgentBot
-  operationId: listAgentBots
-  summary: List all agentbots
-  description: List all available agentbots for the current installation
-  responses:
-    200:
-      description: Success
-      schema:
-        type: Array
-        description: 'List of agent bots'
-        $ref: '#/definitions/agent_bot'
-    404:
-      description: Inbox not found, Agent bot not found
-    403:
-      description: Access denied
+tags:
+  - Account AgentBots
+operationId: list-all-account-agent-bots
+summary: List all AgentBots
+description: List all agent bots available for the current account
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of agent bots'
+      items:
+        - $ref: '#/definitions/agent_bot'
+
+  401:
+    description: Unauthorized

swagger/paths/agent_bots/show.yml

@@ -0,0 +1,14 @@
+tags:
+  - Account AgentBots
+operationId: get-details-of-a-single-account-agent-bot
+summary: Get an agent bot details
+description: Get the details of an agent bot in the account
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
+  404:
+    description: The given agent bot ID does not exist in the account

swagger/paths/agent_bots/update.yml

@@ -0,0 +1,18 @@
+tags:
+  - Account AgentBots
+operationId: update-an-account-agent-bot
+summary: Update an agent bot
+description: Update an agent bot's attributes
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized

swagger/paths/inboxes/get_agent_bot.yml

@@ -0,0 +1,21 @@
+get:
+  tags:
+    - Inbox
+  operationId: getInboxAgentBot
+  summary: Show Inbox Agent Bot
+  description: See if an agent bot is associated to the Inbox
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: ID of the inbox
+      required: true
+  responses:
+    204:
+      description: Success
+      schema:
+        $ref: '#/definitions/agent_bot'
+    404:
+      description: Inbox not found, Agent bot not found
+    403:
+      description: Access denied

swagger/paths/inboxes/index.yml

@@ -10,7 +10,8 @@ get:
       schema:
         type: array
         description: 'Array of inboxes'
-        $ref: '#/definitions/inbox'
+        items:
+          $ref: '#/definitions/inbox'
     404:
       description: Inbox not found
     403:

swagger/paths/index.yml

@@ -1,61 +1,138 @@
+# ------------  Platform API routes  ------------#
+
+# Accounts
+
+platform/api/v1/accounts:
+  post:
+    $ref: ./platform/accounts/create.yml
+platform/api/v1/accounts/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './platform/accounts/show.yml'
+  patch:
+    $ref: ./platform/accounts/update.yml
+  delete:
+    $ref: ./platform/accounts/delete.yml
 
 
+# Account Users
 
-# Inboxes
-/accounts/{account_id}/inboxes:
-  $ref: ./inboxes/index.yml
-/accounts/{account_id}/inboxes/:
-  $ref: ./inboxes/create.yml
-/accounts/{account_id}/inboxes/{id}:
-  $ref: ./inboxes/update.yml
-/accounts/{account_id}/inboxes/{id}/set_agent_bot:
-  $ref: ./inboxes/set_agent_bot.yml
+platform/api/v1/accounts/{id}/account_users:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './platform/account_users/index.yml'
+  post:
+    $ref: ./platform/account_users/create.yml
+  delete:
+    $ref: ./platform/account_users/delete.yml
+
+# AgentBots
+
+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}:
+  parameters:
+    - $ref: '#/parameters/agent_bot_id'
+  get:
+    $ref: './platform/agent_bots/show.yml'
+  patch:
+    $ref: ./platform/agent_bots/update.yml
+  delete:
+    $ref: ./platform/agent_bots/delete.yml
+
+# Users
+
+platform/api/v1/users:
+  post:
+    $ref: ./platform/users/create.yml
+platform/api/v1/users/{id}:
+  parameters:
+    - $ref: '#/parameters/user_id'
+  get:
+    $ref: './platform/users/show.yml'
+  patch:
+    $ref: ./platform/users/update.yml
+  delete:
+    $ref: ./platform/users/delete.yml
+platform/api/v1/users/{id}/login:
+  parameters:
+    - $ref: '#/parameters/user_id'
+  $ref: './platform/users/login.yml'
+
+
+# ---------------- end of platform path -----------#
+
+# AgentBots
+
+/api/v1/accounts/{account_id}/agent_bots:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: ./agent_bots/index.yml
+  post:
+    $ref: ./agent_bots/create.yml
+/api/v1/accounts/{account_id}/agent_bots/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/agent_bot_id'
+  get:
+    $ref: './agent_bots/show.yml'
+  patch:
+    $ref: ./agent_bots/update.yml
+  delete:
+    $ref: ./agent_bots/delete.yml
+
+
+# Contacts
+/api/v1/accounts/{account_id}/contacts:
+  $ref: ./contact/list_create.yml
+/api/v1/accounts/{account_id}/contacts/{id}:
+  $ref: ./contact/crud.yml
+/api/v1/accounts/{account_id}/contacts/{id}/conversations:
+  $ref: ./contact/conversations.yml
+/api/v1/accounts/{account_id}/contacts/search:
+  $ref: ./contact/search.yml
+/api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes:
+  $ref: ./contact_inboxes/create.yml
+/api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes:
+  $ref: ./contactable_inboxes/get.yml
 
-/agent_bots:
-  $ref: ./agent_bots/index.yml
 
 # Conversations
-/accounts/{account_id}/conversations:
+/api/v1/accounts/{account_id}/conversations:
   parameters:
     - $ref: '#/parameters/account_id'
   $ref: ./conversation/index_or_create.yml
-
-/accounts/{account_id}/conversations/{converstion_id}:
+/api/v1/accounts/{account_id}/conversations/{converstion_id}:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
   get:
     $ref: ./conversation/show.yml
-
-/accounts/{account_id}/conversations/{conversation_id}/toggle_status:
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
   post:
     $ref: ./conversation/toggle_status.yml
 
-# Messages
-/accounts/{account_id}/conversations/{id}/messages:
-  $ref: ./conversation/messages/create_attachment.yml
-/accounts/{account_id}/conversations/{converstion_id}/messages:
+# Conversations Assignments
+
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
-  get:
-    $ref: ./conversation/messages/index.yml
   post:
-    $ref: ./conversation/messages/create.yml
+    $ref: ./conversation/assignments.yml
 
-/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
-  parameters:
-    - $ref: '#/parameters/account_id'
-    - $ref: '#/parameters/conversation_id'
-    - $ref: '#/parameters/message_id'
-  delete:
-    $ref: ./conversation/messages/delete.yml
+# Conversation Labels
 
-
-/accounts/{account_id}/conversations/{conversation_id}/labels:
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
@@ -64,46 +141,71 @@
   post:
     $ref: ./conversation/labels/create.yml
 
-/accounts/{account_id}/conversations/{conversation_id}/assignments:
+
+# Inboxes
+/api/v1/accounts/{account_id}/inboxes:
+  $ref: ./inboxes/index.yml
+/api/v1/accounts/{account_id}/inboxes/:
+  $ref: ./inboxes/create.yml
+/api/v1/accounts/{account_id}/inboxes/{id}:
+  $ref: ./inboxes/update.yml
+/api/v1/accounts/{account_id}/inboxes/{id}/agent_bot:
+  $ref: ./inboxes/get_agent_bot.yml
+/api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot:
+  $ref: ./inboxes/set_agent_bot.yml
+
+
+# Messages
+/api/v1/accounts/{account_id}/conversations/{id}/messages:
+  $ref: ./conversation/messages/create_attachment.yml
+/api/v1/accounts/{account_id}/conversations/{converstion_id}/messages:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/conversation_id'
+  get:
+    $ref: ./conversation/messages/index.yml
   post:
-    $ref: ./conversation/assignments.yml
+    $ref: ./conversation/messages/create.yml
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+    - $ref: '#/parameters/message_id'
+  delete:
+    $ref: ./conversation/messages/delete.yml
 
-# Contacts
-/accounts/{account_id}/contacts:
-  $ref: ./contact/list_create.yml
 
-/accounts/{account_id}/contacts/{id}:
-  $ref: ./contact/crud.yml
 
-/accounts/{account_id}/contacts/{id}/conversations:
-  $ref: ./contact/conversations.yml
+# Integrations
+/api/v1/accounts/{account_id}/integrations/apps:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './integrations/apps/show.yml'
+/api/v1/accounts/{account_id}/integrations/hooks:
+  post:
+    $ref: './integrations/hooks/create.yml'
+  patch:
+    $ref: ./integrations/hooks/update.yml
+  delete:
+    $ref: ./integrations/hooks/delete.yml
 
-/accounts/{account_id}/contacts/search:
-  $ref: ./contact/search.yml
-
-/accounts/{account_id}/contacts/{id}/contact_inboxes:
-  $ref: ./contact_inboxes/create.yml
-/accounts/{account_id}/contacts/{id}/contactable_inboxes:
-  $ref: ./contactable_inboxes/get.yml
 
 
 # Profile
 /profile:
   $ref: ./profile/index.yml
 
+
 # Teams
-/accounts/{account_id}/teams:
+/api/v1/accounts/{account_id}/teams:
   parameters:
     - $ref: '#/parameters/account_id'
   get:
     $ref: ./teams/index.yml
   post:
     $ref: ./teams/create.yml
-
-/accounts/{account_id}/teams/{id}:
+/api/v1/accounts/{account_id}/teams/{id}:
   parameters:
     - $ref: '#/parameters/account_id'
     - $ref: '#/parameters/team_id'
@@ -114,19 +216,3 @@
   delete:
     $ref: ./teams/delete.yml
 
-
-# Integrations
-/accounts/{account_id}/integrations/apps:
-  parameters:
-    - $ref: '#/parameters/account_id'
-  get:
-    $ref: './integrations/apps/show.yml'
-  
- 
-/accounts/{account_id}/integrations/hooks:
-  post:
-    $ref: './integrations/hooks/create.yml'
-  patch:
-    $ref: ./integrations/hooks/update.yml
-  delete:
-    $ref: ./integrations/hooks/delete.yml

swagger/paths/integrations/apps/show.yml

@@ -7,7 +7,10 @@ responses:
   200:
     description: Success
     schema:
-      $ref: '#/definitions/integrations_app'
+      type: array
+      description: 'Array of Integration apps'
+      items:
+        $ref: '#/definitions/integrations_app'
   401:
     description: Unauthorized
   404:

swagger/paths/platform/account_users/create.yml

@@ -0,0 +1,40 @@
+tags:
+  - Account Users
+operationId: create-an-account-user
+summary: Create an Account User
+description: Create an Account User
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      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:
+    description: Success
+    schema:
+      properties: 
+        account_id:
+          type: integer
+          description: The ID of the user
+        user_id:
+          type: integer
+          description: The ID of the user
+        role:
+          type: string
+          description: whether user is an administrator or agent
+      
+  401:
+    description: Unauthorized

swagger/paths/platform/account_users/delete.yml

@@ -0,0 +1,26 @@
+tags:
+  - Account Users
+operationId: delete-an-account-user
+summary: Delete an Account User
+description: Delete an Account User
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      properties: 
+        user_id:
+          type: integer
+          description: The ID of the user
+          required: true
+
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The account does not exist

swagger/paths/platform/account_users/index.yml

@@ -0,0 +1,28 @@
+tags:
+  - Account Users
+operationId: list-all-account-users
+summary: List all Account Users
+description: List all account users
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of account users'
+      items:
+        type: object
+        properties: 
+          account_id:
+            type: integer
+            description: The ID of the user
+          user_id:
+            type: integer
+            description: The ID of the user
+          role:
+            type: string
+            description: whether user is an administrator or agent
+      
+  401:
+    description: Unauthorized

swagger/paths/platform/accounts/create.yml

@@ -0,0 +1,20 @@
+tags:
+  - Accounts
+operationId: create-an-account
+summary: Create an Account
+description: Create an Account
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/account_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/platform_account'
+  401:
+    description: Unauthorized

swagger/paths/platform/accounts/delete.yml

@@ -0,0 +1,14 @@
+tags:
+  - Accounts
+operationId: delete-an-account
+summary: Delete an Account
+description: Delete an Account
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The account does not exist

swagger/paths/platform/accounts/show.yml

@@ -0,0 +1,16 @@
+tags:
+  - Accounts
+operationId: get-details-of-an-account
+summary: Get an account details
+description: Get the details of an account
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/platform_account'
+  401:
+    description: Unauthorized
+  404:
+    description: The given account does not exist

swagger/paths/platform/accounts/update.yml

@@ -0,0 +1,20 @@
+tags:
+  - Accounts
+operationId: update-an-account
+summary: Update an account
+description: Update an account's attributes
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/account_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/platform_account'
+  401:
+    description: Unauthorized

swagger/paths/platform/agent_bots/create.yml

@@ -0,0 +1,20 @@
+tags:
+  - AgentBots
+operationId: create-an-agent-bot
+summary: Create an Agent Bot
+description: Create an agent bot
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized

swagger/paths/platform/agent_bots/delete.yml

@@ -0,0 +1,14 @@
+tags:
+  - AgentBots
+operationId: delete-an-agent-bot
+summary: Delete an AgentBot
+description: Delete an AgentBot
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The agent bot does not exist

swagger/paths/platform/agent_bots/index.yml

@@ -0,0 +1,17 @@
+tags:
+  - AgentBots
+operationId: list-all-agent-bots
+summary: List all AgentBots
+description: List all agent bots available
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of agent bots'
+      items:
+        $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized

swagger/paths/platform/agent_bots/show.yml

@@ -0,0 +1,16 @@
+tags:
+  - AgentBots
+operationId: get-details-of-a-single-agent-bot
+summary: Get an agent bot details
+description: Get the details of an agent bot
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
+  404:
+    description: The given agent bot ID does not exist

swagger/paths/platform/agent_bots/update.yml

@@ -0,0 +1,20 @@
+tags:
+  - AgentBots
+operationId: update-an-agent-bot
+summary: Update an agent bot
+description: Update an agent bot's attributes
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized

swagger/paths/platform/users/create.yml

@@ -0,0 +1,20 @@
+tags:
+  - Users
+operationId: create-a-user
+summary: Create a User
+description: Create a User
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/user_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/user'
+  401:
+    description: Unauthorized

swagger/paths/platform/users/delete.yml

@@ -0,0 +1,14 @@
+tags:
+  - Users
+operationId: delete-a-user
+summary: Delete a User
+description: Delete a User
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The user does not exist

swagger/paths/platform/users/login.yml

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

swagger/paths/platform/users/show.yml

@@ -0,0 +1,16 @@
+tags:
+  - Users
+operationId: get-details-of-a-user
+summary: Get an user details
+description: Get the details of an user
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/user'
+  401:
+    description: Unauthorized
+  404:
+    description: The given user does not exist

swagger/paths/platform/users/update.yml

@@ -0,0 +1,20 @@
+tags:
+  - Users
+operationId: update-a-user
+summary: Update a user
+description: Update a user's attributes
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/user_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/user'
+  401:
+    description: Unauthorized

swagger/paths/teams/index.yml

@@ -9,6 +9,7 @@ responses:
     schema:
       type: array
       description: 'Array of teams'
-      $ref: '#/definitions/team'
+      items:
+        $ref: '#/definitions/team'
   401:
     description: Unauthorized