OpenAPI Schema's
Understanding and writing Schemas
An OpenAPI schema, also known as an OpenAPI specifcation or Swagger file, is a structured way to describe the interface of an API, detailing its endpoints, operations, parameters, and responses. It serves as an instruction manual for interacting with the API, defining how to communicate with it and what to expect in response. To create an Action you have to add a schema to the action. The chatbot will use the schema as a blueprint to generate URLs and requests. The schema will help the chatbot to understand the Action. It is important to write a clear schema for your chatbot. Within a schema, 5 different actions can be executed by the chatbot. If you want the chatbot to execute more actions, you have to create a new Action.
In this article, we will give you some tips and tricks on how to write the best schema for your chatbot.
1. Open API Version
Add the version of the OpenAPI used. For Watermelon the minimum Open AI Version is 3.0. Example:
openapi: "3.0.0"
2. Info:
We advise you to integrate the word chatbot in the title when adding general information for your chatbot. Add the name of your integration in the description so it is easy to find back when having multiple yaml files. Example:
info:
title: "Chatbot Integration"
version: "1.0.0"
description: "Integration between Returnless and the chatbot to enhance product efficiency"
3. Servers:
Write down the different URL's where the API is available. If your API is running on multiple servers, add all URLs. You can add a description per URL for example for different environments, this is optional. Example:
openapi: "3.0.0"
info:
title: "Example API with server security"
version: "1.0.0"
servers:
- url: "https://api.example.com/v1"
description: "Production Environment"
- url: "https://staging.api.example.com/v1"
description: "Staging Environment"
4. Path tips and tricks
Within the reference part of the API documentation, you can find what the API can do. The references are usually divided by request. Per request, you can find exactly which parameters are needed to execute the request. For each topic you can create a path.
If the topic is not in the API documentation, it is not possible to create an Action for it.
-
Check your parameters: Within a chat, the parameters will trigger the action. Check your API documentation which parameters are required to execute the action and add all required parameters in the path. Check the following:
- Check if multiple parameters are required. If so, make sure that all parameters are in your schema. It might be needed to add an instruction to the chatbot's Domain Knowledge that he requests all parameters from the end user. If not all parameters are given to the chatbot, the Action cannot be executed.
Example instruction: When someone asks for their order status, ask for the order ID and the email address of the customer. - Check the location of your parameter: Path parameters are part of the URL itself, query parameters are added at the end of the URL, and header parameters are sent in the request headers.
- Query parameters are appended to the URL and are typically used to filter or search for specific data (e.g., ?orderId=123). The location of the parameter needs to show in the schema like this: in: query
If you add a query parameter in header, the Interactive tester will show an error when testing the Action. - Path parametersThese are part of the URL path and typically identify specific resources. E.g. webbshoporderid is the path parameter in this path: /order/{webshoporderid}
- Header parameters are included in the HTTP header and are not specified in the schema. They contain metadata about the request, like authentication tokens or content type. Within Watermelon this information can be added when creating an Action e.g. the Authentication tokens can be added in the authentication fields.
- Query parameters are appended to the URL and are typically used to filter or search for specific data (e.g., ?orderId=123). The location of the parameter needs to show in the schema like this: in: query
- Check the spelling of the parameters:Always copy and paste the parameters from the API documentation. A capital letter can already give incorrect results back from the API.
- Check if multiple parameters are required. If so, make sure that all parameters are in your schema. It might be needed to add an instruction to the chatbot's Domain Knowledge that he requests all parameters from the end user. If not all parameters are given to the chatbot, the Action cannot be executed.
-
Use unique action names : When adding multiple requests in one schema, make sure to use unique action/path names. If action names are too similar, the chatbot might get confused which path to take. Example of good names:
-
Check your summary: Check if you added a summary. Example: Retrieve order details by order number
-
Check your description: Check if you added a description, this tells the chatbot which information to get from the API. Example: Retrieve detailed information about a specific order using the order number.
-
Add responses: Per path, add the responses the API can give. You can use these responses to test your chatbot. You can test your Action in the interactive tester. When the chatbot gives you an error, you can add the following in the Domain Knowledge: When the API Action fails, provide the response from the API.
By doing this, you might find out why your Action is not working.
Example of a good path:
paths:
/orders.json:
get:
summary: Retrieve order details by order number
description: Retrieve detailed information about a specific order using the order number.
parameters:
- in: query
name: number
required: true
schema:
type: string
description: The order number to retrieve details for.
responses:
'200':
description: Successful response with order details
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Order not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5. Components
When writing up your components, always include examples for each property. These examples have to be available in your system, this can be test data from a test account. Example:
components:
schemas:
Order:
type: object
properties:
id:
type: integer
example: 275248911
createdAt:
type: string
format: date-time
example: 2024-06-18T16:12:07+02:00
updatedAt:
type: string
format: date-time
example: 2024-06-18T16:46:47+02:00
number:
type: string
example: ORD146123
status:
type: string
example: completed_shipped
channel:
type: string
example: main
priceExcl:
type: number
format: float
example: 96.32
priceIncl:
type: number
format: float
example: 116.55
Updated about 2 months ago