Merge pull request #5729 from Thisara-Welmilla/update-sms-docs

Update custom sms provider configuration guidelines.

Author: Thisara-Welmilla

en/asgardeo/docs/apis/organization-apis/restapis/notification-senders-v2.yaml

@@ -407,6 +407,9 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SMSProviderList'
+              examples:
+                ListOfSMSProviderResponseExample:
+                  $ref: '#/components/examples/SMSProvidersListResponseExample'
         "400":
           description: Bad Request
           content:
@@ -457,25 +460,27 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/SMSSenderAdd'
-            example:
-              provider: NEXMO
-              providerURL: https://rest.nexmo.com/sms/json
-              key: 123**45
-              secret: 5tg**ssd
-              sender: +94 775563324
-              type : json
-              properties:
-                - key: body.scope
-                  value: "internal"
-                - key: http.headers
-                  value: "X-Version: 1, Authorization: bearer ,Accept: application/json ,Content-Type: application/json"
+            examples:
+              TwilioSMSProviderRequestExample:
+                $ref: '#/components/examples/TwilioSMSProviderRequestExample'
+              VonageSMSProviderRequestExample:
+                $ref: '#/components/examples/VonageSMSProviderRequestExample'
+              CustomSMSProviderRequestExample:
+                $ref: '#/components/examples/CustomSMSProviderRequestExample'
       responses:
         "201":
           description: Successful Response
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/SMSSender'
+              examples:
+                TwilioSMSProviderResponseExample:
+                  $ref: '#/components/examples/TwilioSMSProviderResponseExample'
+                VonageSMSProviderResponseExample:
+                  $ref: '#/components/examples/VonageSMSProviderResponseExample'
+                CustomSMSProviderResponseExample:
+                  $ref: '#/components/examples/CustomSMSProviderResponseExample'
         "400":
           description: Bad Request
           content:
@@ -563,6 +568,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SMSSender'
+              examples:
+                TwilioSMSProviderResponseExample:
+                  $ref: '#/components/examples/TwilioSMSProviderResponseExample'
+                VonageSMSProviderResponseExample:
+                  $ref: '#/components/examples/VonageSMSProviderResponseExample'
+                CustomSMSProviderResponseExample:
+                  $ref: '#/components/examples/CustomSMSProviderResponseExample'
         "400":
           description: Bad Request
           content:
@@ -623,18 +635,13 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/SMSSenderUpdateRequest'
-            example:
-              provider: NEXMO
-              providerURL: https://rest.nexmo.com/sms/json
-              key: 123**45
-              secret: 5tg**ssd
-              sender: +94 775563324
-              type : json
-              properties:
-                - key: body.scope
-                  value: "internal"
-                - key: http.headers
-                  value: "X-Version: 1, Authorization: bearer ,Accept: application/json ,Content-Type: application/json"
+            examples:
+              TwilioSMSProviderRequestExample:
+                $ref: '#/components/examples/TwilioSMSProviderRequestExample'
+              VonageSMSProviderRequestExample:
+                $ref: '#/components/examples/VonageSMSProviderRequestExample'
+              CustomSMSProviderRequestExample:
+                $ref: '#/components/examples/CustomSMSProviderRequestExample'
         required: true
       responses:
         "200":
@@ -643,6 +650,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SMSSender'
+              examples:
+                TwilioSMSProviderResponseExample:
+                  $ref: '#/components/examples/TwilioSMSProviderResponseExample'
+                VonageSMSProviderResponseExample:
+                  $ref: '#/components/examples/VonageSMSProviderResponseExample'
+                CustomSMSProviderResponseExample:
+                  $ref: '#/components/examples/CustomSMSProviderResponseExample'
         "400":
           description: Bad Request
           content:
@@ -1192,6 +1206,8 @@ components:
         secret:
           type: string
           example: 5tg**ssd
+        authentication:
+          $ref: '#/components/schemas/Authentication'
         sender:
           type: string
           example: +94 775563324
@@ -1282,6 +1298,8 @@ components:
         sender:
           type: string
           example: +94 775563324
+        authentication:
+          $ref: '#/components/schemas/Authentication'
         contentType:
           type: string
           enum:
@@ -1334,6 +1352,8 @@ components:
         secret:
           type: string
           example: 5tg**ssd
+        authentication:
+          $ref: '#/components/schemas/Authentication'
         sender:
           type: string
           example: +94 775563324
@@ -1397,6 +1417,67 @@ components:
         id:
           type: integer
           format: int64
+    Authentication:
+      type: object
+      description: >
+        The type of authentication required by the action's endpoint. The following options are supported:  
+        
+        - CLIENT_CREDENTIAL: Client credential authentication.<br>
+            ``{
+            "type": "CLIENT_CREDENTIAL",
+            "properties": {
+              "clientId": "3e172dd2-901b-43a9-a26a-728466795f01",
+              "clientSecret": "83cdc120-ccf6-4163-a4a8-c1ba3e872daa",
+              "tokenEndpoint": "https://custom.sms.provider/auth/token",
+              "scopes": "send_scope"
+            }
+          }`` 
+        - BASIC: Username and password based authentication.<br>
+          ``{
+            "type": "BASIC",
+            "properties": {
+              "username": "admin",
+              "password": "admin123"
+            }
+          }``
+        - BEARER: Token based based authentication.<br>
+          ``{
+            "type": "BEARER",
+            "properties": {
+              "token": "83cdc120-ccf6-4163-a4a8-c1ba3e872daa"
+            }
+          }``
+        - API_KEY: API key secret based authentication.<br>
+          ``{
+            "type": "API_KEY",
+            "properties": {
+              "header": "auth",
+              "value": "123ert45"
+            }
+          }``
+      required:
+        - type
+      properties:
+        type:
+          type: string
+          enum:
+            - CLIENT_CREDENTIAL
+            - BASIC
+            - BEARER
+            - API_KEY
+            - NONE
+          example: CLIENT_CREDENTIAL
+        properties:
+          type: object
+          description: Authentication properties specific to the selected type.
+          additionalProperties: true
+      example:
+        type: CLIENT_CREDENTIAL
+        properties:
+          clientId: 3e172dd2-901b-43a9-a26a-728466795f01
+          clientSecret: 83cdc120-ccf6-4163-a4a8-c1ba3e872daa
+          tokenEndpoint: https://custom.sms.provider/auth/token
+          scopes: send_scope
   parameters:
     typeQueryParam:
       name: type
@@ -1409,6 +1490,9 @@ components:
       schema:
         type: string
   securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
     OAuth2:
       type: oauth2
       flows:
@@ -1515,3 +1599,134 @@ components:
             value: "Identity Server"
           - key: "userName"
             value: "iam"
+    TwilioSMSProviderRequestExample:
+      summary: Post and PUT request for Twilio SMS Provider
+      value:
+        provider: Twilio
+        sender: +94 775563324
+        type : json
+        properties:
+          - key: body.scope
+            value: "internal"
+          - key: http.headers
+            value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+        authentication:
+          type: BASIC
+          properties:
+            username: "123ert45"
+            password: "5tg-rts-ssd"
+    VonageSMSProviderRequestExample:
+      summary: Post and PUT request for Vonage SMS Provider
+      value:
+        provider: Vonage
+        sender: +94 775563324
+        type: json
+        properties:
+          - key: body.scope
+            value: "internal"
+          - key: http.headers
+            value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+        authentication:
+          type: BASIC
+          properties:
+            username: "123ert45"
+            password: "5tg-rts-ssd"
+    CustomSMSProviderRequestExample:
+      summary: Post and PUT request for Custom SMS Provider
+      value:
+        provider: Custom
+        sender: +94 775563324
+        type: json
+        properties:
+          - key: body.scope
+            value: "internal"
+          - key: http.headers
+            value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+        authentication:
+          type: CLIENT_CREDENTIAL
+          properties:
+            clientId: 3e172dd2-901b-43a9-a26a-728466795f01
+            clientSecret: 83cdc120-ccf6-4163-a4a8-c1ba3e872daa
+            tokenEndpoint: https://custom.sms.provider/auth/token
+            scopes: send_scope
+    TwilioSMSProviderResponseExample:
+      summary: Response for Twilio SMS Provider
+      value:
+        name: SMSPublisher
+        provider: Twilio
+        key: 123ert45
+        secret: 5tg-rts-ssd
+        sender: +94 775563324
+        type: json
+        properties:
+          - key: body.scope
+            value: "internal"
+          - key: http.headers
+            value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+        authentication:
+          type: BASIC
+          properties:
+            username: "123ert45"
+            password: "5tg-rts-ssd"
+    VonageSMSProviderResponseExample:
+      summary: Response for Vonage SMS Provider
+      value:
+        name: SMSPublisher
+        provider: Vonage
+        key: 123ert45
+        secret: 5tg-rts-ssd
+        sender: +94 775563324
+        type: json
+        properties:
+          - key: body.scope
+            value: "internal"
+          - key: http.headers
+            value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+        authentication:
+          type: BASIC
+          properties:
+            username: "123ert45"
+            password: "5tg-rts-ssd"
+    CustomSMSProviderResponseExample:
+      summary: Response for Custom SMS Provider
+      description: This document specifies a **RESTful API** for **WSO2 Identity Server Notification Senders**
+      value:
+        name: SMSPublisher
+        provider: Custom
+        key: ""
+        secret: ""
+        sender: +94 775563324
+        type: json
+        properties:
+          - key: body.scope
+            value: "internal"
+          - key: http.headers
+            value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+        authentication:
+          type: CLIENT_CREDENTIAL
+          properties:
+            clientId: 3e172dd2-901b-43a9-a26a-728466795f01
+            clientSecret: 83cdc120-ccf6-4163-a4a8-c1ba3e872daa
+            tokenEndpoint: https://custom.sms.provider/auth/token
+            scopes: send_scope
+    SMSProvidersListResponseExample:
+      summary: Response for list of SMS Provider
+      value:
+        - name: SMSPublisher
+          provider: Custom
+          key: ""
+          secret: ""
+          sender: +94 775563324
+          type: json
+          properties:
+            - key: body.scope
+              value: "internal"
+            - key: http.headers
+              value: "X-Version: 1, Accept: application/json, Content-Type: application/json"
+          authentication:
+            type: CLIENT_CREDENTIAL
+            properties:
+              clientId: 3e172dd2-901b-43a9-a26a-728466795f01
+              clientSecret: 83cdc120-ccf6-4163-a4a8-c1ba3e872daa
+              tokenEndpoint: https://custom.sms.provider/auth/token
+              scopes: send_scope