Wat is een OpenAPI-specificatie?

OpenAPI-specificatie, voorheen bekend als Swagger, beschrijft verschillende aspecten van een API. Een OpenAPI-specificatie (specificatie) beschrijft de eindpunten, parameters en antwoorden van de API. OpenAPI-specificaties worden geschreven in YAML of JSON en worden gebruikt door hulpprogramma's voor het genereren van documentatie, testcases en clientbibliotheken. Door een OpenAPI-specificatie te hebben, kunnen API-bouwers ervoor zorgen dat hun API nauwkeurig wordt beschreven, toegankelijker en eenvoudiger te integreren in een breed scala aan toepassingen en services.

Daarom moet u overwegen om een OpenAPI-specificatie voor uw API te hebben:

• Documenteer een API op een gestandaardiseerde manier. Documenteer een API-specificatie in een consistente en door mensen leesbare indeling.
• Genereer een client-SDK. Gebruik hulpprogramma's zoals Kiota om het genereren van clientbibliotheken in verschillende programmeertalen te automatiseren.
• Maak een mock-API. Maak mockservers op basis van de API-specificatie, die u helpt tijdens de vroege ontwikkelingsfasen wanneer de werkelijke API nog niet is geïmplementeerd.
• Verbeter de samenwerking. Bied verschillende teams (front-end, back-end, QA) met een duidelijk inzicht in de mogelijkheden en beperkingen van de API, zodat nieuwe teamleden snel kunnen worden opgepakt.
• Vereenvoudig testen en valideren. Automatiseer de validatie van API-aanvragen en -antwoorden op basis van de specificatie, waardoor verschillen gemakkelijker kunnen worden geïdentificeerd.
• Integreren met API Management-hulpprogramma's. Integreer, implementeer en bewaak uw API's eenvoudig met veel API Management-hulpprogramma's en gateways, zoals Azure API Center en Azure API Management.
• Vereenvoudig de CONFIGURATIE van de API-gateway. Gebruik OpenAPI-specificaties om API-gateways te configureren en taken te automatiseren, zoals routering, transformaties en instellingen voor het delen van cross-origin-resources.

Met behulp van OpenAPI-specificaties kunt u API's maken die goed zijn ontworpen en consistent zijn gedocumenteerd. Ze zijn ook beter onderhoudbaar en gemakkelijker te gebruiken zowel intern als door externe consumenten.

Hebt u nog geen OpenAPI-specificatie?

Het schrijven van een specificatie met de hand voor een API die al bestaat, neemt tijd in beslag en het wijkt af van wat de API echt doet. Een andere optie is om vast te leggen wat de API retourneert en om de specificatie daarvan te genereren.

Approach	Wat u krijgt	Waar moet ik naar kijken?
Schrijf het met de hand	Volledige controle over beschrijvingen en voorbeelden	Het kost tijd en het wijkt af van de echte API
Genereer het op basis van codeaantekeningen	Een specificatie die gesynchroniseerd blijft met uw code	U hebt toegang nodig tot de CODE van de API en het framework moet dit ondersteunen
Genereer het op basis van opgenomen verkeer	Een specificatie voor elke API die u kunt aanroepen, inclusief api's waarvan u geen eigenaar bent	Hierin worden alleen de verzoeken behandeld die u hebt vastgelegd, dus gebruik de onderdelen van de API die u nodig hebt

Dev Proxy registreert de verzoeken en antwoorden tussen uw app en een API en genereert hiervan een OpenAPI-specificatie. Zie Een OpenAPI-specificatie genereren voor de stappen.

Volgende stap

Een OpenAPI-specificatie genereren