Om een Actie te maken, moet je een schema toevoegen aan de actie. In dit artikel zullen we uitleggen wat een schema is en begeleiding bieden over hoe je een schema kunt schrijven.
Wat is een Schema?
Een OpenAPI-schema, ook wel bekend als een OpenAPI-specificatie of Swagger-bestand, is een gestructureerde manier om de interface van een API te beschrijven, waarbij de endpoints, operaties, parameters en antwoorden worden gedetailleerd. Het dient als een handleiding voor interactie met de API, waarin wordt gedefinieerd hoe ermee te communiceren en wat te verwachten als antwoord.
Het Schrijven van een Schema
Hieronder staat een basisvoorbeeld van een Schema in YAML-formaat, in overeenstemming met OpenAPI-versie 3.0.0, inclusief de belangrijkste componenten die je vaak zult gebruiken:
openapi: 3.0.0
info:
title: Voorbeeld API
description: Dit is een voorbeeld van een OpenAPI-specificatie.
version: "1.0.0"
servers:
- url: https://exampleapi.com/
paths:
/items:
get:
summary: Lijst van items
description: Haalt een lijst van items op.
responses:
'200':
description: Een lijst van items.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: "Item 1"
post:
summary: Maak een item aan
description: Maakt een nieuw item aan.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "Nieuw Item"
responses:
'201':
description: Succesvol een nieuw item aangemaakt.
components:
schemas:
Item:
type: object
properties:
id:
type: integer
name:
type: string
Belangrijkste Componenten van een OpenAPI Schema
- openapi: Specificeert de versie van de gebruikte OpenAPI-specificatie. Het schema moet minstens OpenAPI-versie 3.0.0 compatibel zijn.
- info: Bevat basisinformatie over de API, zoals titel, beschrijving en versie.
- servers: Lijst van servers waar de API beschikbaar is, inclusief basis-URL's.
- paths: Definieert beschikbare endpoints en HTTP-methoden voor communicatie met de API. Elk pad specificeert operaties en parameters.
- responses: Beschrijft mogelijke antwoorden na het maken van verzoeken aan een endpoint.
- components/schemas: Hiermee kun je modellen definiëren die in je API worden gebruikt, waardoor herbruikbaarheid en organisatie worden vergemakkelijkt.
Het Valideren van het Schema
Voordat je het schema voor je AI-actie gebruikt, is het essentieel om het te valideren om ervoor te zorgen dat het aan de noodzakelijke normen voldoet en vrij is van fouten. Klik op 'Valideren' om te zien of je schema is gevalideerd. Als dat niet het geval is, zie je hieronder de fouten en kun je ze corrigeren.
Zodra het schema de validatie doorstaat, worden de beschikbare acties eronder weergegeven. Deze acties vertegenwoordigen de functionaliteiten die in je schema zijn gedefinieerd en zijn klaar om te worden gebruikt in je chatbot. Het testen van deze acties zorgt ervoor dat je chatbot nauwkeurig kan reageren op gebruikersvragen en de gewenste taken kan uitvoeren.
