Publiceren van API documentatie (als statische content met mogelijkheden voor extra voorbeelden, uitleg, etc)

[marcvanandel]

Voor maximale integratiemogelijkheden en toegankelijkheid voor anderen om te integreren is documentatie essentieel. De huidige Open API documentatie toegankelijk via Swagger UI is een mooi start ... maar dat kan beter en onafhankelijk van een omgeving gepubliceerd worden. Hierbij moet wel rekening gehouden worden met het automatisch genereren vanuit de code, zodat aanpassingen van de API wel zorgen voor up to date documentatie (op alle plekken).

Suggesties en ideeën:

• https://github.com/Redocly/redoc
  • Voorbeeld: https://www.pdok.nl/restful-api/-/article/terugmeldingen-1
• Gitbook 😉
• data.overheid.nl (en developer.overheid.nl)

[kad-busses]

Mogelijk alternatief is ook https://mrin9.github.io/RapiDoc/, lijstje met voor- en nadelen staan op https://github.com/mrin9/RapiDoc/issues/141 (in de rapidoc repo, dus wellicht niet helemaal objectief). Weet niet of we RapiDoc moeten doen, is meer om aan te geven dat er ook alternatieven zijn