-
Notifications
You must be signed in to change notification settings - Fork 7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
(semi) automatisch valideren, resolveer en code genereren #41
Comments
Om dit te doen moet je eerst lokaal swagger-cli en swagger-codegen installeren. Vervolgens kan je in een repository een script (.bat voor Windows, .command voor Mac, .sh voor Linux) zetten in de map "code". Voor Mac en Linux ziet dat er bijvoorbeeld (voor BRK) zo uit: base_path=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )
In bovenstaand script wordt:
Het valt me wel op dat de resolved versie afwijkt van hoe het nu resolved is, bijvoorbeeld door ander gebruik van aanhalingstekens. Ook is de manier van opnemen extern gedefinieerde componenten heel anders. |
we hebben trouwens ook op sommige plekken Postman collecties opgenomen in de repository, zoals in BRK. Maar die is niet bijgehouden. Dus bijvoorbeeld nu in versie 1.0.0 komt de Postman collectie niet overeen met de OAS3 specificatie. Dus ook daarvoor moeten we een geautomatiseerde oplossing vinden, of een stuk strakkere procedure om ook dit synchroon te houden, of (wanneer we denken dit niet te kunnen) het gewoon verwijderen? |
automatisch genereren postman collectie kan door het aan bovenstaand script toevoegen van bijvoorbeeld:
|
De door swagger-cli gebundelde openapi.yaml kan niet worden gebruikt in nswagstudio. Dit komt door gegenereerde $ref-s die er als volgt uit zien:
|
Ik heb de oplossing gevonden. Resolven kan blijkbaar ook met swagger-codegen:
|
Wanneer er wijzigingen worden gedaan aan de yaml voor een API, moeten we nu handmatig (in Swagger o.i.d.) deze yaml valideren en een resolved versie maken.
Dit is extra werk en bovendien zien we dat vaak wijzigingen alleen worden doorgevoerd op de beheer-yaml en er pas na een aantal (grotere) wijzigingen een nieuwe resolved versie wordt gemaakt.
Via één opdracht (al dan niet in een script of batch bestand) kun je het valideren en resolven automatiseren. Bijvoorbeeld met https://www.npmjs.com/package/swagger-cli.
Het is bovendien mogelijk dit te koppelen aan een pre-commit hook, zodat bij een commit automatisch wordt gecheckt of de te committee yaml wel valide is.
Hiernaast is het voor gebruikers erg handig wanneer er al SDK's beschikbaar zijn. Dan hoeven ze zelf de code niet te genereren. Ik denk dat developers veel blijer worden van een SDK dan van een yaml specificatie.
SDK's genereren kan ook geautomatiseerd, met bijvoorbeeld https://github.com/swagger-api/swagger-codegen
The text was updated successfully, but these errors were encountered: