To create an Action you have to add a schema to the action. In this article we will explain what a schema is and provide guidance on how to write a schema.
What is a Schema?
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.
Writing a Schema
Below is a basic example of an Schema in YAML format, compliant with OpenAPI version 3.0.0, including the key components you will often use:
openapi: 3.0.0
info:
title: Example API
description: This is an example of an OpenAPI specification.
version: "1.0.0"
servers:
- url: https://exampleapi.com/
paths:
/items:
get:
summary: List of items
description: Retrieves a list of items.
responses:
'200':
description: A list of items.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: "Item 1"
post:
summary: Create an item
description: Creates a new item.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "New Item"
responses:
'201':
description: Successfully created a new item.
components:
schemas:
Item:
type: object
properties:
id:
type: integer
name:
type: string
Key Components of an OpenAPI Schema
- openapi: Specifies the version of the OpenAPI specification being used. The schema must be at least OpenAPI version 3.0.0 compliant.
- info: Contains basic information about the API, such as title, description, and version.
- servers: Lists servers where the API is available, including base URLs.
- paths: Defines available endpoints and HTTP methods for communication with the API. Each path specifies operations and parameters.
- responses: Describes possible responses after making requests to an endpoint.
- components/schemas: Allows you to define models used throughout your API, aiding in reusability and organization.
Validating the Schema
Before using the schema for your AI Action, it's essential to validate it to ensure it meets the necessary standards and is free from errors. Click 'Validate' to see if your schema is validated. If it is not, you will see the errors below and you can correct them.
Once the schema passes validation, the available actions will show underneath. These actions represent the functionalities defined in your schema and are ready to be used in your chatbot. Testing these actions ensures that your chatbot can accurately respond to user inquiries and perform the desired tasks.
