Writing an Open API 2.0 Schema for Salesforce Enhanced External Service

{
  "swagger": "2.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
    "definitions": {
    "User": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "phones":{
          "type":"array",
          "items":{
             "type": "object",
             "$ref": "#/definitions/Phone"
          }
        }
      }
    },
      "Phone":{
      "properties":{
        "typeofphone":{
          "type":"string"
        },
        "phone":{
          "type":"string"
        }
      }
    }
  },
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Returns a user by ID.",
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "required": true,
            "type": "integer"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Creates a new user.",
        "parameters": [
          {
            "in": "body",
            "name": "user",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

Now let’s look at  the HTTP Request of Send Mail Graph API that is being referred from Graph API Docs :

POST https://graph.microsoft.com/v1.0/me/sendMail
Content-type: application/json

{
"message": {
"subject": "Meet for lunch?",
"body": {
"contentType": "Text",
"content": "The new cafeteria is open."
},
"toRecipients": [
{
"emailAddress": {
"address": "fannyd@contoso.onmicrosoft.com"
}
}
],
"ccRecipients": [
{
"emailAddress": {
"address": "danas@contoso.onmicrosoft.com"
}
}
]
},
"saveToSentItems": "false"
}

Now we are going to update the sample Open API with the details from the above Send Mail () graph API.Let’s work on the sample Open API code and update lines 1 to 12 to below code snippet Refer Host, Basepath from line 1 of the Graph API code and enter title and description as per the name you wish..

{
"swagger": "2.0",
"info": {
"title": "Outlook API",
"description": "Outlook API",
"version": "1.0.0"
},
"host": "graph.microsoft.com",
"basePath": "/v1.0",
"schemes": [
"https"
],

We will deal with the Definition part from line 13 to 41 in the later section of the blog.

Now let’s look at the ‘Paths‘ Section and update line 41 to 63 to below code snippet:

"paths": {
"/me/sendMail": {
"post": {
"summary": "Send a Mail",
"parameters": [
{
"in": "body",
"name": "email",
"schema": {
"$ref": "#/definitions/Email"
}
}

Below is the explanation forthe above code snippet –

Email": {
"type": "object",
"properties": {
"message": {
"$ref": "#/definitions/Message"
}

In the above code, Type is Object and $ref – a reference to another definition. As I mentioned earlier, We need to work on from outer braces to inner braces, here is the definition for the message –

"Message": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"body": {
"$ref": "#/definitions/Body"
},

Similarly, repeat the process to the innermost curly braces and then merge the entire code. Once you merge the code, make sure you check for any syntax error by copy-pasting the code to Swagger Editor.

Your merged Open API Schema should look like below  :

{
"swagger": "2.0",
"info": {
"title": "Outlook API",
"description": "Outlook API",
"version": "1.0.0"
},
"host": "graph.microsoft.com",
"basePath": "/v1.0",
"schemes": [
"https"
],
"definitions": {
"Email": {
"type": "object",
"properties": {
"message": {
"$ref": "#/definitions/Message"
}
}
},
"Message": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"body": {
"$ref": "#/definitions/Body"
},
"toRecipients": {
"type": "array",
"items": {
"$ref": "#/definitions/Recipient"
}
}
}
},
"Body": {
"type": "object",
"properties": {
"contentType": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"Recipient": {
"type": "object",
"properties": {
"emailAddress": {
"$ref": "#/definitions/EmailAddress"
}
}
},
"EmailAddress": {
"type": "object",
"properties": {
"address": {
"type": "string"
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"paths": {
"/me/sendMail": {
"post": {
"summary": "Send a Mail",
"parameters": [
{
"in": "body",
"name": "email",
"schema": {
"$ref": "#/definitions/Email"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Error",
}
}
}
}
}
}

I hope you have understood now how we can create an Open API 2.0 Schema.

Using Open API 2.0 Schema in the Enhanced External Services in Salesforce

Now we can just go ahead and register an enhanced External Service by using this Schema.

Go to Set Up – > External Service and Set it up as instructed in the below screenshot :

1. Enter Name – Outlook
2. Select the Name Credentials Set up from the previous blog – Explore Graph API by connecting Microsoft Azure and Salesforce.
3. Copy Paste the created Open API Schema
4. Hit Save

I hope you now know how to register an Open API Schema on your own. In the next blog, I would demonstrate how you can use this External Service created via Flow.

References :

1. Open API Schema Examples – Salesforce Help Documentation
2. MS Graph API Send Email () – Microsoft Documentation
3. Swagger Editor – Swagger Open Source Documentation
4. Exploring Graph API by connecting Microsoft Azure and Salesforce
5. Exploring Open API 2.0 and Swagger Tools
6. Register an External Service in Salesforce – Trailhead