Ondersteuning voor OpenAPI Specification 3.0

Laatst bijgewerkt: 20-10-2026

Ontwerp een API met OpenAPI Specification (OAS) 3.0 met behulp van API-contracten.

OpenAPI Specification 3.0 bevat nieuwe functies, wat API-ontwerpers meer expressiviteit en productiviteit biedt.

Voor meer informatie over OpenAPI, zie de Swagger-documentatie.

Componenten

Met componenten kunt u verschillende elementen binnen een API hergebruiken. Deze elementen kunnen zijn:

Padvariabelen
Queryparameters
Kopteksten
Antwoorden

Combinaties

Met combinaties kunt u een nieuw gegevenstype maken door verschillende andere gegevenstypen te combineren. API Contracts ondersteunt twee typen combinaties:

Compositie (allOf) stelt u in staat om schema-eigenschappen uit verschillende schema's te aggregeren. U kunt bijvoorbeeld een gegevenstype Company definiëren door alle eigenschappen van de bestaande typen Contact en Error te hergebruiken.
Polymorfisme (oneOf/anyOf) stelt u in staat een entiteit te maken die de eigenschappen van verschillende gegevenstypen kan gebruiken.
- oneOf stelt u in staat om een gegevenstype te definiëren dat de eigenschappen van een van de geselecteerde typen bevat. Als u bijvoorbeeld een bewerking maakt om informatie over een serviceaccount op te halen, kunt u de respons definiëren met behulp van de combinatie oneOf om ofwel alle eigenschappen van Error of alle eigenschappen van ServiceAccountCount op te halen.
- anyOf stelt u in staat om een gegevenstype te definiëren dat de eigenschappen van een of meer van de geselecteerde typen bevat. U kunt bijvoorbeeld een gegevenstype nervousSystem en een type skeleton met verschillende eigenschappen definiëren, en de combinatie anyOf gebruiken om een gegevenstype te maken dat eigenschappen van een van deze typen bevat.
  Een anyOf-combinatie is geldig zolang deze alle vereiste parameters van ten minste één van de geselecteerde gegevenstypen bevat. Het onderstaande voorbeeld gebruikt de eigenschap brain_weight van het type nervousSystem en de eigenschappen skull_height en teeth van skeleton.

Voor meer informatie over compositie en polymorfisme, zie Overerving en polymorfisme en Verschil tussen anyOf en oneOf.

Antwoorden

OAS 3.0 stelt u in staat om nieuwe typen responsen te definiëren voor uw bewerkingen:

Responsbereiken: in plaats van een respons zoals 200 te definiëren, kunt u deze instellen als 2XX, zodat deze responsen van 200 tot 299 bevat.
Standaardresponsen: u kunt een standaardrespons definiëren die wordt geretourneerd wanneer een specifieke respons of bereikrespons niet is gedefinieerd.

Responsberichten gedefinieerd met een expliciete code hebben voorrang op responsbereiken en standaardresponsberichten, en responsbereiken hebben voorrang op standaardresponsberichten. In het volgende voorbeeld:

De 204-respons is gedefinieerd en heeft voorrang op de overige.
De 2XX-respons is van toepassing op responscodes 200 tot 203 en 205 tot 299.
De standaardrespons is van toepassing op alle 1XX-, 3XX-, 4XX- en 5XX-responsen.

Beveiliging

OAS 3.0 introduceert nieuwe beveiligingsschema's voor uw API:

Bearer-authenticatie
OpenIdConnect

Beperkingen

OAS 3.0 stelt u in staat om aan te geven dat sommige eigenschappen alleen-lezen of alleen-schrijven zijn.

Deze optie is alleen beschikbaar in gegevenstypen en kan niet worden gedefinieerd in aanvragen of antwoorden op bewerkingsniveau.

Was deze pagina nuttig?

Als u problemen ervaart op deze pagina of de inhoud onjuist is – een tikfout, een ontbrekende stap of een technische fout – laat het ons weten!

Geef hier uw feedback