Om gebruikers de mogelijkheden van een api te laten ontdekken, is het mogelijk om overzichtelijke documentatie te genereren aan de hand van een OpenAPI-document. Er zijn diverse tools in het OpenAPI-ecosysteem die daar ondersteuning voor bieden. Deze tools lezen het OpenAPI-document uit en kunnen zodoende alle mogelijke operaties overzichtelijk weergeven. Voor dit voorbeeld wordt gebruikgemaakt van Redoc, met ruim elfduizend stars op Github een van de populairste libraries met betrekking tot het genereren van documentatie op basis van OAS. Het wordt onder andere gebruikt om de Docker Engine API te documenteren.
Redoc is gebouwd in React. Een van de manieren om het te gebruiken is door de React-library in te laden via een cdn. Voor deze demo heb ik de specificatie geüpload als Github-gist. Onderstaand HTML-document is voldoende om onze documentatie te renderen in een browser.
<!DOCTYPE html> <html lang="en"> <head> <title>API Docs</title> </head> <body> <redoc spec-url="https://gist.githubusercontent.com/TijmenWierenga/ 53975a5e8dd3395437be3d6399ef5f46/raw/d0faf2f3bbd482cea952b4a57bcce8ef6fce0876/ openapi.yaml"></redoc> <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script> </body> </html>
Het resultaat ziet er zo uit in de browser:
/i/2004130388.png?f=imagegallery)