POC schema first design met OAS met Redocly

[CathyDingemanse]

Ik stel voor om een Proof of Concept te doen met Redocly om te evalueren of deze tool
ons helpt bij (de overdracht van) het doorontwikkelen van onze API specificaties waarbij de klant het uitgangspunt is.

Wij gebruiken daarvoor de 30 dagen trial periode die Redocly ons ter beschikking stelt.
In deze 30 dagen proberen antwoord te krijgen op de volgende vragen:

1. verbetert Redocly het versiebeheer van de OAS specificatie?
2. verbetert Redocly de koppeling van de schema's met de documentatie (is er sprake van een betere ontkoppeling/beheerbaarheid)?
3. Is het mogelijk om de Open API spec te previewen tijdens de ontwikkeling? Nu moet steeds een link worden toegevoegd naar een variant in ontwikkeling
4. wat zijn de governance voordelen? Is de standaard werkwijze van Redocly bruikbaar in ons project, en hoe gemakkelijk is het om deze werkwijze te volgen, en vergemakkelijkt dit de overdracht naar de staande organisatie en de adoptie van de werkwijze?
5. vergemakkelijkt Revel het content management van de developer portal, en welke klantwaarde levert het (meertaligheid etc.)
6. hoe gemakkelijk is het om scheiding aan te brengen tussen verschillende productfuncties en scheiding aan te brengen in externe en interne deverloper portals?
7. hoe gemakkelijk is het om de content in Gitlab te beheren?

[nielskorporaal]

Hier is meer informatie te vinden over het beheren van remote content in Redocly

https://redocly.com/docs/realm/setup/how-to/remote-content

[MelvLee]

brp-api developer portal gepubliceerd met redocly: https://brp-api.redocly.app/

1. Redocly gebruikt 'git' voor versiebeheer. Voor het beheren van meerdere versies van een API kan gebruik worden gemaakt van version subfolders. Zie https://redocly.com/docs/realm/author/how-to/versions#create-version-subfolders
2. ...
3. Het is mogelijk om te previewen. Dit kan met alle content en configuratie (bijv. navigatie). Hiervoor open je in de editor de Webview en klik vervolgens op de Open in a new window button
4. ...
5. ...
6. Catalogs kan worden gebruikt om api definities organiseren. In de project zijn 2 catalogs gedefinieerd: 'BRP API catalog' en 'internal api catalog'. In de 'internal api catalog' is bijv. de gezag-api opgenomen. TODO: RBAC gebruiken om 'internal api catalog' af te schermen
7. Een git repo kan eenvoudig worden gekoppeld aan een Redocly project. Dit wordt gedaan via Project Settings > Git hosting.