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.

  1. 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:

    1. 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.
    2. 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.
    3. 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.
  2. 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:

  3. Check your summary: Check if you added a summary. Example: Retrieve order details by order number

  4. 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.

  5. 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