5.9.1. Opstellen OpenAPI Description (OAD)

Een OpenAPI Description (hierna OAD) is in AOS altijd onderdeel van een AFD-definitie (alleen AFD 2.0). Om een nieuwe OAD op te stellen klik je op het pijltje van de dropdown rechts in de knop ‘Open’ en kies ‘Specificeer OpenAPI Description’.

Specificeer OAD

In het scherm verschijnen twee kolommen. Het linkerdeel toont de (boom-)structuur van het OAD-document met klikbare items. Per aangeklikt item kunnen in het rechterdeel van het scherm de eigenschappen in het betreffende OpenAPI object worden ingevoerd.

Info
In de sectie ‘Info’ dienen de titel en het versienummer van de OAD te staan. Een OAD heeft een eigen versienummer (dat kan verschillen van het versienummer van de AFD-definitie).

Voer info-elementen in

Servers
In de sectie ‘Servers’ dient de URL naar de betreffende API-server te staan. Klik hiervoor op de knop Toevoegen, vul de URL van de server in en kies Opslaan. Het is mogelijk hier meerdere URL’s toe te voegen. Om een URL te verwijderen klik je op het rode prullenbak-icoon.

Voeg server toe

Voer url van server in

Paths
In de sectie ‘Paths’ staat aangegeven welke endpoints (resources) de API bevat, zoals bijvoorbeeld: /Policy. Binnen een OAD kunnen meerdere paden/endpoints worden beschreven. Het toevoegen van een endpoint kan gemakkelijk door te klikken op het plus-symbool of door op de knop ‘Toevoegen’ te klikken in het OpenAPI object. Een endpoint kan je verwijderen door te klikken op het rode prullenbak-icoon.

Voer Paths in of pas deze aan

Instellingen per endpoint
Je kunt een zelfgedefinieerd endpoint openklappen en daaronder de volgende onderdelen invullen:

Servers
In de sectie ‘Servers’ kan een eventueel voor dit endpoint afwijkende URL naar de betreffende API-server worden opgenomen. Invoer die op dit niveau plaatsvindt, overrulet invoer op een hoger niveau. Het is mogelijk hier meerdere URL’s in op te nemen. Een URL kan je verwijderen door te klikken op het rode prullenbak-icoon.

Voer url van alternatieve server in

Parameters
In de sectie ‘Parameters’ beschrijf je de generieke path- of queryparameters. Per parameter specifieer je de naam (name), de locatie (in), gegevenstype (type). Houd er rekening mee dat het onderdeel Parameters een array is, wat betekent dat in YAML elke parameterdefinitie wordt vermeld met een streepje (-) ervoor.

Voer hier de parameters in of pas deze aan

Operations
In de sectie ‘Operations’ geef je aan welke HTTP-methodes mogelijk zijn om op het pad te zetten. De mogelijkheden zijn: GET, PUT, POST en PATCH. Je selecteert deze door te klikken op de gewenste knop.
Per geselecteerde operatie is het in de uitklapbare boom in de linkerkolom nu mogelijk deze te selecteren en verder te configureren in het OpenAPI object (rechter kolom).

Selecteer operaties

Instellingen per operatie

Configureer de operatie door de operatie te selecteren in de boom

Per operatie kan je de volgende zaken ingeven:

Description
Beschrijf het doel van de operatie.

Request body
Request bodies worden gewoonlijk gebruikt bij “create” en “update” operations (POST, PUT, PATCH). De request body wordt gespecificeerd door het selecteren van de betreffende functie binnen de AFD-definitie. Het (AFD-) schema van deze functie bevat de specificatie van het request. Met de ‘Required-switch’ geef je aan of deze verplicht is.

Parameters
In de sectie ‘Parameters’ beschrijf je de specifieke path- of queryparameters voor deze operatie. Per parameter specificeer je de naam (name), de locatie (in), gegevenstype (type). Houd er rekening mee dat het onderdeel Parameters een array is, wat betekent dat in YAML elke parameterdefinitie wordt vermeld met een streepje (-) ervoor. Invoer die op dit niveau plaatsvindt, overrulet invoer op een hoger niveau.

Voer hier de parameters voor deze operatie in of pas deze aan

Responses
In de sectie ‘Responses’ geef je aan welke responses verwacht mogen worden. Voor elke operatie moet een response worden geconfigureerd aan de hand van een HTTP-statuscode en data die terugkomen in de response body. Ook hier is het mogelijk een functie van de betreffende AFD-definitie als response body te selecteren. Vooralsnog ondersteunt AOS alleen HTTP-status 200 – OK.

Servers
In deze sectie ‘Servers’ wordt een eventueel voor deze operatie afwijkende URL naar de betreffende API-server opgenomen. Invoer die op dit niveau plaatsvindt, overrulet invoer op een hoger niveau. Een URL kan je verwijderen door te klikken op het rode prullenbak-icoon.

Voeg eventueel afwijkende server toe