Begrip en het schrijven van Schemas

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

  1. openapi: Specificeert de versie van de gebruikte OpenAPI-specificatie. Het schema moet minstens OpenAPI-versie 3.0.0 compatibel zijn.
  2. info: Bevat basisinformatie over de API, zoals titel, beschrijving en versie.
  3. servers: Lijst van servers waar de API beschikbaar is, inclusief basis-URL's.
  4. paths: Definieert beschikbare endpoints en HTTP-methoden voor communicatie met de API. Elk pad specificeert operaties en parameters.
  5. responses: Beschrijft mogelijke antwoorden na het maken van verzoeken aan een endpoint.
  6. 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.

Screenshot 2024-04-17 at 09.16.41