(semi) automatisch valideren, resolveer en code genereren

[melsk-r]

Originally created by fsamwel (https://github.com/VNG-Realisatie/Haal-Centraal-common/issues/41):

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

[melsk-r]

This comment originally might have been created by someone else.

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:

!/bin/bash

base_path=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P ) cd "$base_path"

#!/bin/bash

base_path=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )
cd "$base_path"

if swagger-cli validate ../specificatie/BRK-Bevragen/openapi.yaml | tee /dev/stderr | grep -q "is valid"; then
  swagger-cli bundle -o ../specificatie/BRK-Bevragen/genereervariant/openapi.yaml -t yaml ../specificatie/BRK-Bevragen/openapi.yaml
  swagger-cli bundle -o ../specificatie/BRK-Bevragen/genereervariant/openapi.json -t json ../specificatie/BRK-Bevragen/openapi.yaml

  rm -R java
  mkdir java
  swagger-codegen generate -i ../specificatie/BRK-Bevragen/openapi.yaml -l java -o java

  rm -R csharp-dotnet2
  mkdir csharp-dotnet2
  swagger-codegen generate -i ../specificatie/BRK-Bevragen/openapi.yaml -l csharp-dotnet2 -o csharp-dotnet2

  rm -R python
  mkdir python
  swagger-codegen generate -i ../specificatie/BRK-Bevragen/openapi.yaml -l python -o python
fi

In bovenstaand script wordt:

1. de API specificatie gevalideerd. Volgende stappen worden alleen gedaan wanneer de specs valide zijn
2. een resolved (genereer) versie gemaakt in yaml en json
3. voor elke gewenste taal de client code gegenereerd (hier als voorbeelden C#, Java en Python, maar is makkelijk uit te breiden).

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. @MelvLee zou jij eens willen kijken naar de resolved/genereerversie van de yaml of die bruikbaar is in deze vorm? openapi.yaml.zip En of de gegenereerde code goed is (die is niet gemaakt op basis van de resolved versie, maar op basis van de beheersversie met externe links)? csharp-dotnet2.zip

[melsk-r]

This comment originally might have been created by someone else.

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? Wellicht via https://www.npmjs.com/package/openapi-to-postmanv2?

[melsk-r]

This comment originally might have been created by someone else.

automatisch genereren postman collectie kan door het aan bovenstaand script toevoegen van bijvoorbeeld:

openapi2postmanv2 -s ../specificatie/BRK-Bevragen/openapi.yaml -o ../docs/BRK-Bevragen-postman-collection.json

[melsk-r]

This comment originally might have been created by someone else.

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:

#/paths/~1kadastraalonroerendezaken/get/parameters/0

[melsk-r]

This comment originally might have been created by someone else.

Ik heb de oplossing gevonden. Resolven kan blijkbaar ook met swagger-codegen:

  #genereer resolved yaml: 
  swagger-codegen generate -i ../specificatie/BRK-Bevragen/openapi.yaml -l openapi-yaml -o ../specificatie/BRK-Bevragen/genereervariant
  #genereer resolved json:
  swagger-codegen generate -i ../specificatie/BRK-Bevragen/openapi.yaml -l openapi -o ../specificatie/BRK-Bevragen/genereervariant
  #verwijder door codegen toegevoegde dingen die niet nodig zijn:
  rm -R ../specificatie/BRK-Bevragen/genereervariant/.swagger-codegen
  rm ../specificatie/BRK-Bevragen/genereervariant/.swagger-codegen-ignore
  rm ../specificatie/BRK-Bevragen/genereervariant/README.md