REST API’s documenteren: OpenAPI, RAML of Blueprint API?
Stagiair | 13 maart 2019
Stagiair | 13 maart 2019
REST API’s1: je kunt er niet omheen. Vrijwel iedere ontwikkelaar krijgt er vroeg of laat mee te maken. Maar hoe documenteer je een REST API? Veelgebruikte combinaties zijn OpenAPI en Swagger UI of RAML en API Console. In dit artikel zal ik allereerst de verschillende standaarden voor het beschrijven van REST API’s met elkaar vergelijken. Vervolgens bespreek ik de tools die beschikbaar zijn voor het opzetten van documentatie.
Er zijn drie grote spelers op het gebied van API-specificatie standaarden:
Hoe zit het met de populariteit van deze drie? Dit is van belang omdat hoe groter het aantal actieve gebruikers is, hoe groter de kans is dat er mensen (en bedrijven) zijn die bijdragen aan de verbetering van de tools rondom deze standaarden. Denk aan tools om interactieve documentatie te genereren, of geautomatiseerd endpoints te testen.
Onderstaande tabel geeft een vergelijking van het aantal sterren op Github. Alhoewel dit niet alles zegt, is het wel een indicator van de populariteit van de standaard in verhouding tot de andere standaarden.
Zoals je kunt zien zijn ze allemaal gestegen, maar is OpenAPI het meest gegroeid: met 50,5%. Daarnaast kun je zien dat OpenAPI op dit moment bijna twee keer zoveel sterren heeft als de nummer twee: API Blueprint. OpenAPI heeft dus én de meeste sterren, én is de afgelopen tijd het meest gegroeid.
Qua functionaliteiten zijn de drie vrijwel gelijk. Alle drie zijn ze gericht op het beschrijven van de structuur van een REST API. In OpenAPI kan dit met YAML of JSON, in Blueprint API met Markdown, en in RAML met YAML. Alle drie ondersteunen ze de omschrijving van authenticatiemogelijkheden als OAuth 2.0 en API keys in de header. De keuze hangt dus af van een persoonlijke voorkeur. Hierbij kun je wel rekening houden met het aantal actieve gebruikers, de beschikbare tools eromheen en of er actieve ontwikkeling plaatsvindt.
Rondom elke standaard is een collectie van Open Source oplossingen beschikbaar voor het genereren van interactieve documentatie. Er bestaan voor elke standaard tientallen, maar voor dit blog heb ik de meest gebruikte gekozen.
OpenAPI: Swagger UI
RAML: API Console
Blueprint API: Apiary
Hier is Swagger UI de populairste van de drie. Swagger UI wordt dan ook nog actief onderhouden en er zijn honderden mensen die hebben bijgedragen aan Swagger UI op Github. En ook al zijn API Console en Apiary oorspronkelijk gebouwd voor respectievelijk RAML en Blueprint API, ze accepteren beide ook OpenAPI specificaties! Alle drie geven ze een overzicht van de API endpoints, de benodigde parameters voor die endpoints en een mogelijkheid om de endpoints te testen met een klik op de knop.
Voorbeeld van documentatie in Swagger UI
Zoals uit het voorgaande blijkt is er geen directe winnaar. Alle drie zijn ze gericht op en geschikt voor het beschrijven van de structuur van een REST API. Ze ondersteunen allemaal de basisfunctionaliteiten van moderne REST API’s. Het hangt af van jouw persoonlijke voorkeur. Geen enkele standaard is inherent beter dan de ander. Wel heeft OpenAPI het grootste aantal gebruikers en bestaat er een uitgebreid ecosysteem van tools die OpenAPI ondersteunen. Ook tools die gebouwd zijn voor RAML en Blueprint API, zoals API Console en Apiary, werken met een OpenAPI beschrijving. Mijn persoonlijke voorkeur gaat daarom uit naar OpenAPI in combinatie met Swagger UI.
1 Een API staat voor ‘Application Programming Interface’. Via een API kunnen applicaties/programma’s met elkaar communiceren. Het ene programma kan via de API van het andere programma bijvoorbeeld gegevens opvragen van dat programma. Een REST API is een API die volgens een bepaalde architecturale stijl is opgebouwd: REST.
