Ondersteuning voor OpenAPI Specification 3.0

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

OpenAPI Specification 3.0 wordt geleverd met 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 in een API hergebruiken. Deze elementen kunnen zijn:

Padvariabelen
Queryparameters
Headers
Reacties

Combinaties

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

Met compositie (allOf) kunt u schema-eigenschappen uit verschillende schema's samenvoegen. U kunt bijvoorbeeld een gegevenstype Company definiëren door alle eigenschappen van de bestaande typen Contact en Error te hergebruiken.
Met polymorfisme (oneOf/anyOf) kunt u een entiteit maken die de eigenschappen van verschillende gegevenstypen kan gebruiken.
- oneOf kunt u een gegevenstype 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 reactie definiëren met behulp van de combinatie oneOf om ofwel alle eigenschappen van Error of alle eigenschappen van ServiceAccountCount op te halen.
- anyOf kunt u een gegevenstype definiëren dat de eigenschappen van een of meer van de geselecteerde typen bevat. U kunt bijvoorbeeld een gegevenstype nervousSystem en een type skeleton definiëren die verschillende eigenschappen bevatten, en de combinatie anyOf gebruiken om een gegevenstype te maken dat willekeurige eigenschappen van een van deze typen bevat.
  Een combinatie anyOf is geldig zolang deze alle vereiste parameters van ten minste een 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 Inheritance and Polymorphism en Difference Between anyOf and oneOf.

Reacties

Met OAS 3.0 kunt u nieuwe typen reacties voor uw bewerkingen definiëren:

Reactiebereiken: in plaats van een reactie zoals 200 te definiëren, kunt u deze instellen als 2XX, zodat deze reacties van 200 tot 299 omvat.
Standaardreacties: u kunt een standaardreactie definiëren die moet worden geretourneerd wanneer een specifieke reactie of een reactiebereik niet is gedefinieerd.

Reacties die zijn gedefinieerd met een expliciete code hebben voorrang op reactiebereiken en standaardreacties, en reactiebereiken hebben voorrang op standaardreacties. In het volgende voorbeeld:

De reactie 204 is gedefinieerd en heeft voorrang op de andere.
De reactie 2XX is van toepassing op reactiecodes 200 tot 203 en 205 tot 299.
De default-reactie is van toepassing op alle 1XX-, 3XX-, 4XX- en 5XX-reacties.

Beveiliging

OAS 3.0 biedt nieuwe beveiligingsschema's voor uw API:

Bearer-authenticatie
OpenIdConnect

Beperkingen

Met OAS 3.0 kunt u aangeven dat sommige eigenschappen alleen-lezen of alleen-schrijven zijn.

Deze optie is alleen beschikbaar in gegevenstypen en kan niet worden gedefinieerd in verzoeken of reacties 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