Open andrea-scarcella-81 opened 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.
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 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:
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.
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.
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"
]
}
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.
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.