hofmanj
commented
6 months ago Wij lopen met de generatie van onze code tegen soortgelijke problemen aan. Het genereren van Java code (de taal waarmee onze API's gemaakt worden) uit de aangeleverde JSON-schema's, waar de entiteiten in staan beschreven, lukt niet goed.
Ik heb een aantal dingen waar wij tegenaan lopen allemaal in één melding gezet, maar deze issues kunnen altijd opgedeeld worden per 'onderdeel'. Voor nu leek het mij handig om de discussie over code generatie op een plek te houden.
Achtergrond
Het lijkt te komen doordat OpenAPI in versie 3.1.0 een subset van JSON-schema functionaliteit ondersteund. Er is wel een verbetering ten opzichte van versie 3.0.0, maar OpenAPI kan dus niet alle constructies ondersteunen die in het huidige JSON-schema gedefinieerd zijn. Daarnaast werkt een OpenAPI schema volgens (lichtelijk) andere conventies dan een JSON-schema. Het lijkt er daarom op dat het nodig is om de entiteiten naar een omschrijving volgens de OpenAPI conventie te genereren in plaats van naar een 'algemeen' JSON-schema.
Als tijdelijke oplossing hebben wij besloten om de specificatie handmatig over te zetten naar een YAML-bestand met omschrijvingen die de (door ons gebruikte) OpenAPI Generator wel ondersteund.
Problemen
Problemen in de JSON-schema's waar we tegenaan gelopen zijn bij het genereren van code voor onze API's waarbij bericht 4 uit berichtenstroom 2 als voorbeeld gebruikt wordt:
Generatie van entiteiten
Bij het genereren van code uit het schema wordt de entiteit Rendementsinformatie wel gegenereerd, maar de entiteiten
(properties in het JSON-schema) die daar in zitten, dus CommonFunctional, CommonTechnical, Document, Party en Error, niet en die krijgen het generieke type Object en niet de strongly-typed classes die in de thread hierboven
genoemd zijn. Hierdoor worden alle properties die in deze genoemde entiteiten zitten niet gegenereerd. Voor zover ik
hier iets over kan vinden komt dat doordat de entiteit in de $ref in het JSON-schema beschreven staat, in plaats van
een OpenAPI specificatie.
AllOf, AnyOf, OneOf
Bij het genereren worden de beschrijvingen allOf, anyOf en oneOf niet gezien als een omschrijving van
"subschema's" maar als entiteiten. Voor enumeraties in oneOf staat hier onder een losse probleemomschrijving. Wat
betreft allOf en anyOf, deze zouden op zijn minst in een object met key items moeten staan. Het lukt dan echter
nog steeds niet om de entiteit in de $ref te genereren naar een strongly-typed class omdat ze beschreven staan in
een JSON-schema in plaats van een OpenAPI schema (wat neer komt op het zelfde probleem bij Generatie van entiteiten). Op deze pagina is daar meer over te lezen, al gaat deze documentatie over OpenAPI versie 3.0 en niet over 3.1.
Enumeraties
De structuur voor enumeraties in het JSON-schema wordt niet ondersteund door OpenAPI. Neem bijvoorbeeld het veld
CommonFunctional.Function met de mogelijkheden 01, 02, 03 en 54, die staan omschreven in een lijst met key
oneOf als:
"function": {
"description": "Message function (NL: Berichtfunctie)",
"codelistName": "ADNFUN",
"type": "string",
"oneOf": [
{
"const": "01"
},
{
"const": "02"
},
{
"const": "09"
},
{
"const": "54"
}
]
}Wat volgens de OpenAPI specificatie de omschrijving van een enumeratie is, staat in een lijst met als key enum en als
waarde een lijst van strings. Het veld CommonFunctional.Function zal er met deze opzet als volgt uit zien:
"function": {
"description": "Message function (NL: Berichtfunctie)",
"codelistName": "ADNFUN",
"type": "string",
"enum": [
"01",
"02",
"09",
"54"
]
}Referenties naar webpagina's
In het JSON-schema staan een aantal verwijzingen naar webpagina's in de $ref van properties. Een voorbeeld hiervan is
CommonTechnical.MessageVersion, met een verwijzing naar https://www.sivi.org/afd-online-tool/json/ADNVER.json#/definitions/ADNVER. Met OpenAPI wordt dit in principe wel ondersteund, maar in de code generatoren wordt het helaas niet ondersteund. Er wordt, naast de JSON-schema's van de berichten, ook een JSON-bestand toegevoegd met een omschrijving van bijvoorbeeld de eerder genoemde ADNVER (in het geval van bericht 4 staat dit in het bestand dat eindigt op afdCodelist.json). In het JSON-schema zou dus ook het beste naar de omschrijving van de enumeratie in het JSON-bestand verwezen kunnen worden in plaats van naar URL's. Ook omdat het genereren van API-code niet zou moeten leunen op het hebben van een internetverbinding.
dma61
Hi, My team is working on generating (C#) code from the JSON schema of this message to process data from PUO's and we see that the code being generated is different from what we expect, see example below (this is applicable to multiple collections).
Input:
json schema for the 1a message
Tooling:
The tool we use to generate code is NSwag v14.0.3.0 with the settings in the file linked below. vermogen-nswagger.nswag.json
Expectation:
partyPensionProvider.pension will be a collection of objects of type pensionScheme.
Result:
partyPensionProvider.pension is a collection of objects of type Object (base of type hierarchy, none of the pensionScheme attributes).
Request:
Being able to generate strongly-typed classes from JSON schemas will greatly lower the barrier to adoption and streamline development and maintenance activities. Could you therefore refactor this specification to enable this scenario?
Should you have any questions please do not hesitate to let us know.