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’ vul je de titel, het versienummer, een samenvatting, een beschrijving en een link naar de servicevoorwaarden van de OAD in. De titel en het versienummer zijn verplicht in te vullen. Een OAD heeft een eigen versienummer (dat kan verschillen van het versienummer van de AFD-definitie). De opbouw en werkwijze bij ophoging van het versienummer is gelijk aan die van AFD-definities.
Voer info-elementen in
Info-Contact
Onder de sectie Info (openklappen) vind je de contactinformatie. Hier vul je de naam, eventuele URL en e-mailadres in van de (support-) organisatie.
Voer contact-elementen in
Info-License
Onder de sectie Info (openklappen) vind je de licenseinformatie. Hier vul je een naam en óf een identifier, óf een url voor de license-informatie.
Voer contact-elementen in
Servers
In de sectie ‘Servers’ dient de URL naar de betreffende API-server te staan, aangevuld met de omschrijving. Invoer dient YAML te zijn. Klik hiervoor op de wijzigknop (potloodje) in het OpenAPI Object achter Servers.
Voeg server toe
URL’s dienen als array te worden ingevoerd. In YAML moet elke URL voorafgegaan worden door een koppelteken (-). De knop Toon voorbeeld laat voorbeelden zien van hoe servers ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan. Het is mogelijk hier meerdere URL’s toe te voegen voor bijvoorbeeld verschillende omgevingen. Om een URL te verwijderen verwijder je de registratie uit de tekst.
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 zelfgedefinieerde 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. URL’s dienen als array te worden ingevoerd. In YAML moet elke URL voorafgegaan worden door een koppelteken (-). De knop Toon voorbeeld laat voorbeelden zien van hoe servers ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan. Het is mogelijk hier meerdere URL’s toe te voegen voor bijvoorbeeld verschillende omgevingen. Om een URL te verwijderen verwijder je de registratie uit de tekst.
Alternatieve server
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). Ook kan worden aangegeven of de parameter verouderd (deprecated) is. In geval van een query-parameter is met de boolean ‘AllowReserved’ aan te geven of het toegestaan is om gereserveerde tekens (:/?#[]@!$&’()*+,;=) op te nemen in de parameter-waarde. Houd er rekening mee dat het onderdeel Parameters een array is, wat betekent dat in de output (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, PATCH, DELETE, OPTIONS, HEAD en TRACE. 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.
OperationId
Een operationId is een unieke, machinevriendelijke naam die wordt gebruikt om een specifieke API-bewerking (zoals een GET- of POST-verzoek) te identificeren. Dit is cruciaal voor het automatiseren van taken zoals het genereren van code (zoals client-SDK’s en serverstubs), het routeren van verzoeken, en het creëren van documentatie. Het zorgt voor een stabiele referentie, zelfs als de interne API-paden veranderen.
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). Ook kan worden aangegeven of de parameter verouderd (deprecated) is. In geval van een query-parameter is met de boolean ‘AllowReserved’ aan te geven of het toegestaan is om gereserveerde tekens (:/?#[]@!$&’()*+,;=) op te nemen in de parameter-waarde. Houd er rekening mee dat het onderdeel Parameters een array is, wat betekent dat in de output (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’ configureer je welke responses teruggegeven kunnen worden. Voor elke operatie moet minimaal één response worden geconfigureerd aan de hand van een HTTP-statuscode en data die terugkomt in de response body. Uiteraard is het mogelijk meerdere HTTP-statuscodes te configureren. Per HTTP-statuscode is het optioneel mogelijk een AFD-functie (lees (AFD-) schema) van de betreffende AFD-definitie als response body te selecteren.
De output (YAML) bevat naast de HTTP-statuscode ook de omschrijving van de code. Bijvoorbeeld bij statuscode 500: Internal Server Error. Als je de statuscode koppelt aan een AFD-functie dan wordt in de output ook de verwijzing ($ref) naar het betreffende schema opgenomen. Als je geen koppeling maakt met een AFD-functie (‘No function selected’) wordt alleen de code + omschrijving opgenomen in de output.
Selecteer HTTP-statuscode en koppel optioneel aan AFD-functie
Overzicht van HTTP-statuscodes met al dan niet gekoppelde AFD-functies
Na het openklappen van de operatie kunnen de Security Requirements en (eventueel afwijkende) Servers op operatieniveau worden ingevoerd.
Security
Het security-onderdeel (Security Requirements) onder een operatie bepaalt de vereiste authenticatie- en autorisatiemethoden voor die specifieke API-bewerking, zoals het vereisen van een OAuth2-token of een API-sleutel. Dit zorgt ervoor dat alleen geautoriseerde gebruikers toegang krijgen tot gevoelige data of functies. Het definieert welke beveiligingsschema’s uit de algemene components/securitySchemes-sectie moeten worden toegepast op die operatie.
Voer Security Requirements in
Klik hiervoor op de wijzigknop (potloodje) in het OpenAPI Object achter Security Requirements. Invoer dient YAML te zijn. De knop Toon voorbeeld laat een voorbeeld zien van hoe een Security Requirement ingevoerd kan worden. Kies na juiste invoer voor Opslaan.
Security Requirements
Servers
In de sectie ‘Servers’ kan een eventueel voor deze operatie 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 voor bijvoorbeeld verschillende omgevingen. URL’s dienen als array te worden ingevoerd. In YAML moet elke URL voorafgegaan worden door een koppelteken (-). De knop Toon voorbeeld laat voorbeelden zien van hoe servers ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan. Om een URL te verwijderen verwijder je de registratie uit de tekst.
Voeg eventueel voor deze operatie afwijkende server toe
Tags
De sectie ‘Tags’ onder een operation is bedoeld om operaties logisch te groeperen. Dit helpt bij documentatie, navigatie in UI’s (zoals Swagger UI), filtering, en wordt vaak gebruikt door codegenerators om clients of controllers per “groep” (tag) te maken. Het beïnvloedt niet de routing of het gedrag van je API, het is primair organisatorisch/metadata.
Klik voor het toevoegen of wijzigen op de wijzigknop (potloodje) in het OpenAPI Object achter Tags. Invoer dient YAML te zijn. Tags dienen als array te worden ingevoerd dus in YAML moet elke URL voorafgegaan worden door een koppelteken (-). De knop Toon voorbeeld laat een voorbeeld zien van hoe tags ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan.
Voeg optioneel tags toe aan de operatie
ExternalDocs
De sectie ‘ExternalDocs’ dient om externe documentatie te linken die specifiek is voor die operatie, zoals tutorials, codevoorbeelden, of diepgaande uitleg over authenticatie, paginering, of rate limiting, zodat ontwikkelaars die dieper willen graven dan de basale API-referentie gemakkelijk de juiste bronnen vinden. Het brengt structuur aan door relevante, aanvullende informatie direct bij het endpoint te plaatsen, in plaats van alles in de algemene documentatie te stoppen.
Klik voor het toevoegen of wijzigen op de wijzigknop (potloodje) in het OpenAPI Object achter ExternalDocs. Invoer dient YAML te zijn. De knop Toon voorbeeld laat een voorbeeld zien van hoe ExternalDocs ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan.
Voeg optioneel externalDocs toe aan de operatie
Components
De components-sectie dient als een centrale plek om herbruikbare definities, zoals schema’s, parameters, en responses, op te slaan en te beheren. Dit bevordert code-hergebruik, zorgt voor consistentie en maakt de OAD overzichtelijker, omdat deze definities elders in de specificatie kunnen worden hergebruikt door ernaar te verwijzen.
SecuritySchemes
De SecuritySchemes-sectie definieert op gestandaardiseerde wijze de beveiligingsmethoden die de API ondersteunt. Het is een cruciaal onderdeel voor het beschrijven van hoe clients zich moeten authentiseren bij de API. De hoofdfunctie is het herbruikbaar maken van deze definities, zodat ze elders in de specificatie (zoals op het niveau van de gehele API of voor specifieke endpoints) eenvoudig kunnen worden toegepast.
Selecteer SecuritySchemes in de boomstructuur en klik op het potlood-icoon
Voer SecuritySchemes in
Security op hoofdniveau
Het security-onderdeel op hoofdniveau bepaalt de vereiste authenticatie- en autorisatiemethoden voor alle endpoints (API-calls) binnen de OAD. Het definieert welke beveiligingsschema’s uit de algemene (voorgaande) components/securitySchemes-sectie moeten worden toegepast op alle operaties, tenzij een specifieker beveiligingsbeleid op operation-level (per endpoint) wordt vastgesteld.
Voer hier de globale Security Requirements in
Tags op hoofdniveau
De sectie ‘Tags’ is bedoeld om API-endpoints logisch te groeperen en organiseren, wat de navigatie en leesbaarheid in de documentatie (zoals Swagger UI) verbetert, en om extra context of documentatie per groep te koppelen via description en externalDocs, waardoor de API-referentie beter gestructureerd en bruikbaarder wordt.
Klik voor het toevoegen of wijzigen op de wijzigknop (potloodje) in het OpenAPI Object achter Tags. Invoer dient YAML te zijn. Tags dienen als array te worden ingevoerd dus in YAML moet elke URL voorafgegaan worden door een koppelteken (-). De knop Toon voorbeeld laat een voorbeeld zien van hoe tags ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan.
Voeg optioneel tags toe
ExternalDocs op hoofdniveau
De sectie ‘ExternalDocs’ dient om externe documentatie te linken, zoals tutorials, codevoorbeelden, of diepgaande uitleg over authenticatie, paginering, of rate limiting, om zo ontwikkelaars te helpen de API beter te begrijpen en te gebruiken.
Klik voor het toevoegen of wijzigen op de wijzigknop (potloodje) in het OpenAPI Object achter ExternalDocs. Invoer dient YAML te zijn. De knop Toon voorbeeld laat een voorbeeld zien van hoe ExternalDocs ingevoerd kunnen worden. Kies na juiste invoer voor Opslaan.
Voeg optioneel externalDocs toe
Foutmeldingen/hulp bij invoer
Wanneer onlogische- of ontbrekende gegevens zijn gedetecteerd wordt bovenaan het scherm een foutmelding/hint getoond. Alle meldingen moeten zijn opgelost voordat de OAD kan worden geëxporteerd en gepubliceerd. Door middel van de knop ‘Hide’ is de meldingenbox in te klappen zodat er meer werkruimte in het scherm ontstaat om de invoer te completeren (en indien nodig te corrigeren).
Foutmeldingen worden bovenaan het invoerscherm getoond