Eisen en wensen developer portal

[nielskorporaal]

Requirements en wensen:

1. Meertalige ondersteuning (Nederlands, Engels)
2. RedocLy-documentatie
   • embedded redoc docs
3. Out-of-the-box API-voorbeelden (try-out)
   • In-memory database
   • PostgreSQL-database
   • API mocks aanbieden
4. Fields-tool voor het opstellen van requests
   • dynamisch requests genereren
   • validatie verplichte/optionele velden
   • ondersteuning voor authenticatie tokens (bijv: OAuth)
5. How-to guides (zie Diátaxis) bijvoorbeeld:
   • Hoe kan ik bewoners van een adres tijdens een bepaalde periode opvragen?
   • Hoe kan ik de aanschrijfwijze van personen opvragen?
   • Hoe kan ik de gezagsrelaties van personen opvragen?
6. Referenties (zie Diátaxis) bijvoorbeeld:
   • OpenAPI-specificaties
   • Logisch ontwerp
   • ADR's (Architectural Decision Records)
7. Release notes
   • koppeling met git-repo's
8. Ondersteuning voor een design-first aanpak
   • genereren van PR's op basis van aangepaste of voorgestelde wijzigingen in API-specificaties
9. Zoeken in de documentatie
   • Handig om snel relevante handleidingen, referenties en voorbeelden te vinden
10. Authenticatie
    • API-keys
    • OAuth 2.0
    • bevat instructie voor nieuwe aansluiters
11. Mogelijkheid voor gedeelde componenten
    • Header
    • Navigatie
    • Sidebar
    • Footer
    • etc
12. Een gedeeld thema: Voor uniforme styling is het noodzakelijk dat we één thema opstellen wat op alle documentatie sites gebruikt wordt
13. Meerdere content repositories: Elk team krijgt een of meerdere content repositories ter beschikking waarmee de content kan worden beheerd

Technologie keuzes

• Jekyll, gebruikt remote-theme om gedeelde componenten te beheren
• Gatsby
• NextJS (React)
• Hugo
• Docusaurus (React)
• Antora (AsciiDoc) https://antora.org/

Voor de andere technologien kunnen we gebruik maken van Git Submodules om de gedeelde componenten te beheren. De voorkeur is dan om een modern front-end framework te kiezen, zoals NextJS/Hugo/Docusaurus met ondersteuning voor MDX.

We hebben op dit moment een Proof-of-Concept uitgewerkt met NextJS. Echter, NextJS biedt geen out-of-the-box oplossing voor gedeelde theme en verschillende content repositories. Hiervoor biedt antora een oplossing.

Documentatie site structuur

Het idee is om voor elk team of repository een subdomein in te stellen waarop de documentatie gepubliceerd kan worden, bijvoorbeeld:

• personen.developer.rvig.nl
• bewoning.developer.rvig.nl
• berichten.developer.rvig.nl