Skip to content

Commit bcbbd34

Browse files
joseegman-idoneeajoseegarciaclaude
authored
OpenAPI 3.1 / JSON Schema 2020-12: $ref+description fix and further feature support (#382)
* Support additional OpenAPI 3.1 / JSON Schema 2020-12 features Follow-up to the $ref+description fix, addressing further 3.1 gaps found in an audit of the schema generator. Structural correctness fixes (narrow blast radius; only affect specs using these constructs): - $defs: collect top-level `$defs` as a schema source and resolve `$ref: '#/$defs/...'` (ApiTool.getComponentSchemas). Models under $defs now generate and are referenceable. - prefixItems / items:false: tuple arrays and `items:false` degrade to List<Object> instead of an empty/invalid element type. - type:"null": a scalar null type degrades to Object instead of emitting an invalid `null` Java type. - nullability: a field that is nullable (3.0 `nullable:true` or the 3.1 ["T","null"] idiom) is no longer marked required, so no spurious @NotNull is generated (ApiTool.isNullable). - patternProperties: an object with patternProperties maps to Map<String,V> instead of an empty POJO. - 3.1 binary strings: `contentEncoding` / `contentMediaType` are recognised as binary (MultipartFile), complementing `format: binary`. Adds regression test `testOpenApi31Completeness` covering all of the above. Documented limitations (left non-breaking, deferred as larger work): - multi-type unions still pick the first concrete type (tested behaviour; needs a real union type model); - description/summary/examples propagation (wide blast radius: 51 specs use field-level description); - contains/propertyNames/unevaluated*/dependent*/if-then-else validation (needs new validators; parsed-through today); - info.summary / license.identifier metadata; - $id/$anchor resolution and $schema/$dynamicRef (ignored non-fatally). Bumps version 6.4.2 -> 6.5.0 (new features). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Propagate schema description and example(s) into generated models Carry property-level `description` and `example` (3.0) / `examples` (3.1, first entry) into the generated model classes via the @Schema annotation. This also surfaces the sibling `description` of a `$ref` (OpenAPI 3.1), completing the earlier $ref+description fix. Values are Java-string-escaped in the template. - SchemaFieldObject gains `description`/`example`. - ApiTool.getDescription/getExample (examples[0] fallback). - ModelBuilder applies them at the property choke point (applyMetadata). - templateSchema.ftlh emits `description`/`example` on @Schema when present. Assets across the OpenAPI and AsyncAPI generators are regenerated accordingly. Note: the Lombok model template does not use @Schema, so descriptions are not emitted there (unchanged). Full multiapi-engine suite: 110/110 passing (mvn clean test). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: joseegarcia <jose.garcia@disashop.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 7164d96 commit bcbbd34

30 files changed

Lines changed: 633 additions & 52 deletions

File tree

‎multiapi-engine/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
<groupId>com.sngular</groupId>
66
<artifactId>multiapi-engine</artifactId>
7-
<version>6.4.2</version>
7+
<version>6.5.0</version>
88
<packaging>jar</packaging>
99

1010
<properties>

‎multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/model/SchemaFieldObject.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,8 @@ public class SchemaFieldObject {
2828
private Map<String, String> enumValues;
2929

3030
private Object constValue;
31+
32+
private String description;
33+
34+
private String example;
3135
}

‎multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/ApiTool.java‎

Lines changed: 97 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ public final class ApiTool {
4242

4343
public static final String SCHEMAS = "schemas";
4444

45+
public static final String DEFS = "$defs";
46+
4547
public static final String REQUIRED = "required";
4648

4749
public static final String PARAMETERS = "parameters";
@@ -153,7 +155,21 @@ public static JsonNode getItems(final JsonNode schema) {
153155
}
154156

155157
public static Map<String, JsonNode> getComponentSchemas(final JsonNode openApi) {
156-
return getComponentSchemasByType(openApi, SCHEMAS);
158+
final var schemasMap = getComponentSchemasByType(openApi, SCHEMAS);
159+
// JSON Schema 2020-12 / OpenAPI 3.1: reusable schemas may live under a
160+
// top-level `$defs` object instead of `components/schemas`.
161+
schemasMap.putAll(getDefsSchemas(openApi));
162+
return schemasMap;
163+
}
164+
165+
private static Map<String, JsonNode> getDefsSchemas(final JsonNode openApi) {
166+
final var schemasMap = new HashMap<String, JsonNode>();
167+
if (hasNode(openApi, DEFS)) {
168+
final var defs = getNode(openApi, DEFS);
169+
defs.fieldNames().forEachRemaining(name -> schemasMap.put(
170+
DEFS.toUpperCase() + "/" + StringCaseUtils.titleToSnakeCase(name), getNode(defs, name)));
171+
}
172+
return schemasMap;
157173
}
158174

159175
private static Map<String, JsonNode> getComponentSchemasByType(final JsonNode openApi, final String schemaType) {
@@ -226,7 +242,15 @@ public static String getType(final JsonNode schema) {
226242
return "";
227243
}
228244
final JsonNode typeNode = getNode(schema, "type");
229-
return typeNode.isArray() ? getArrayType(typeNode) : StringUtils.defaultIfEmpty(typeNode.textValue(), "");
245+
if (typeNode.isArray()) {
246+
return getArrayType(typeNode);
247+
}
248+
// OpenAPI 3.1 / JSON Schema 2020-12: a scalar `type: "null"` carries no concrete
249+
// Java type; degrade to object so we never emit an invalid `null` type.
250+
if (TypeConstants.NULL.equalsIgnoreCase(typeNode.textValue())) {
251+
return TypeConstants.OBJECT;
252+
}
253+
return StringUtils.defaultIfEmpty(typeNode.textValue(), "");
230254
}
231255

232256
private static String getArrayType(final JsonNode typeNode) {
@@ -347,17 +371,59 @@ public static boolean isDateTime(final JsonNode schema) {
347371
public static boolean isBinary(final JsonNode schema) {
348372
final boolean isMultipartFile;
349373
if (hasType(schema) && TypeConstants.STRING.equalsIgnoreCase(getType(schema))) {
350-
if (hasNode(schema, FORMAT)) {
351-
isMultipartFile = "binary".equalsIgnoreCase(getNode(schema, FORMAT).textValue());
374+
if (hasNode(schema, FORMAT) && "binary".equalsIgnoreCase(getNode(schema, FORMAT).textValue())) {
375+
isMultipartFile = true;
352376
} else {
353-
isMultipartFile = false;
377+
// OpenAPI 3.1 / JSON Schema 2020-12 replace `format: binary` with the
378+
// `contentEncoding` / `contentMediaType` keywords for binary payloads.
379+
isMultipartFile = hasNode(schema, "contentEncoding") || hasNode(schema, "contentMediaType");
354380
}
355381
} else {
356382
isMultipartFile = false;
357383
}
358384
return isMultipartFile;
359385
}
360386

387+
public static boolean isNullable(final JsonNode schema) {
388+
if (Objects.isNull(schema)) {
389+
return false;
390+
}
391+
// OpenAPI 3.0 `nullable: true`.
392+
if (getNodeAsBoolean(schema, "nullable")) {
393+
return true;
394+
}
395+
// OpenAPI 3.1 idiom: `type: ["<type>", "null"]`.
396+
if (hasType(schema)) {
397+
final JsonNode typeNode = getNode(schema, "type");
398+
if (typeNode.isArray()) {
399+
for (final JsonNode element : typeNode) {
400+
if (TypeConstants.NULL.equalsIgnoreCase(element.asText())) {
401+
return true;
402+
}
403+
}
404+
} else {
405+
return TypeConstants.NULL.equalsIgnoreCase(typeNode.textValue());
406+
}
407+
}
408+
return false;
409+
}
410+
411+
public static boolean hasPatternProperties(final JsonNode schema) {
412+
return hasNode(schema, "patternProperties");
413+
}
414+
415+
public static JsonNode getPatternProperties(final JsonNode schema) {
416+
return getNode(schema, "patternProperties");
417+
}
418+
419+
public static boolean hasPrefixItems(final JsonNode schema) {
420+
return hasNode(schema, "prefixItems");
421+
}
422+
423+
public static JsonNode getPrefixItems(final JsonNode schema) {
424+
return getNode(schema, "prefixItems");
425+
}
426+
361427
public static List<JsonNode> findContentSchemas(final JsonNode schema) {
362428
return hasNode(schema, "content") ? schema.findValues("schema") : Collections.emptyList();
363429
}
@@ -414,6 +480,32 @@ public static JsonNode nodeFromFile(final FileLocation ymlParent, final String f
414480
return om.readTree(file);
415481
}
416482

483+
public static String getDescription(final JsonNode schema) {
484+
return getNodeAsString(schema, "description");
485+
}
486+
487+
public static String getExample(final JsonNode schema) {
488+
// OpenAPI 3.0 uses a single `example`; OpenAPI 3.1 / JSON Schema 2020-12 use an
489+
// `examples` array. Prefer `example`, otherwise take the first `examples` entry.
490+
if (hasNode(schema, "example")) {
491+
return asExampleText(getNode(schema, "example"));
492+
}
493+
if (hasNode(schema, "examples")) {
494+
final JsonNode examples = getNode(schema, "examples");
495+
if (examples.isArray() && examples.elements().hasNext()) {
496+
return asExampleText(examples.elements().next());
497+
}
498+
}
499+
return null;
500+
}
501+
502+
private static String asExampleText(final JsonNode example) {
503+
if (Objects.isNull(example) || example.isNull()) {
504+
return null;
505+
}
506+
return example.isValueNode() ? example.asText() : example.toString();
507+
}
508+
417509
public static boolean hasConst(final JsonNode fieldBody) {
418510
return hasNode(fieldBody, "const");
419511
}

‎multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/ModelBuilder.java‎

Lines changed: 68 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -169,12 +169,12 @@ private static Set<SchemaFieldObject> getFields(
169169
baseDir));
170170
}
171171
} else if (TypeConstants.ARRAY.equalsIgnoreCase(ApiTool.getType(schema))) {
172-
final String itemType = ApiTool.hasRef(ApiTool.getItems(schema)) ? MapperUtil.getPojoNameFromRef(ApiTool.getItems(schema), specFile, null)
173-
: ApiTool.getType(ApiTool.getItems(schema));
174172
fieldObjectArrayList.add(SchemaFieldObject.builder()
175173
.baseName("items")
176-
.dataType(SchemaFieldObjectType.fromTypeList(TypeConstants.ARRAY, itemType))
174+
.dataType(SchemaFieldObjectType.fromTypeList(TypeConstants.ARRAY, resolveArrayItemType(schema, specFile)))
177175
.build());
176+
} else if (ApiTool.hasPatternProperties(schema)) {
177+
fieldObjectArrayList.add(buildPatternPropertiesField(ApiTool.getName(schema), schema, specFile));
178178
} else if (ApiTool.isAllOf(schema)) {
179179
fieldObjectArrayList.addAll(processAllOf(totalSchemas, ApiTool.getAllOf(schema), specFile, compositedSchemas, antiLoopList, baseDir));
180180
} else if (ApiTool.isAnyOf(schema)) {
@@ -209,6 +209,8 @@ private static List<SchemaFieldObject> processFieldObjectList(
209209
fieldObjectArrayList.addAll(processArray(fieldName, className, schema, specFile, totalSchemas, compositedSchemas, antiLoopList, baseDir));
210210
} else if (ApiTool.hasAdditionalProperties(schema)) {
211211
fieldObjectArrayList.addAll(processMap(fieldName, schema, specFile, totalSchemas, compositedSchemas, antiLoopList, baseDir));
212+
} else if (ApiTool.hasPatternProperties(schema)) {
213+
fieldObjectArrayList.add(buildPatternPropertiesField(fieldName, schema, specFile));
212214
} else if (ApiTool.hasRef(schema)) {
213215
fieldObjectArrayList.add(
214216
processRef(fieldName, schema, new SchemaFieldObjectType(MapperUtil.getSimpleType(schema, specFile)), totalSchemas, compositedSchemas, antiLoopList, specFile, baseDir));
@@ -337,9 +339,28 @@ private static List<SchemaFieldObject> processObjectProperty(
337339
} else {
338340
fieldObjectArrayList.addAll(processFieldObjectList(buildingSchema, fieldName, fieldName, fieldBody, specFile, totalSchemas, compositedSchemas, antiLoopList, baseDir));
339341
}
342+
applyMetadata(fieldObjectArrayList, fieldName, fieldBody);
340343
return fieldObjectArrayList;
341344
}
342345

346+
private static void applyMetadata(final List<SchemaFieldObject> fields, final String fieldName, final JsonNode fieldBody) {
347+
final String description = ApiTool.getDescription(fieldBody);
348+
final String example = ApiTool.getExample(fieldBody);
349+
if (Objects.isNull(description) && Objects.isNull(example)) {
350+
return;
351+
}
352+
for (final var field : fields) {
353+
if (Objects.equals(field.getBaseName(), fieldName)) {
354+
if (Objects.nonNull(description)) {
355+
field.setDescription(description);
356+
}
357+
if (Objects.nonNull(example)) {
358+
field.setExample(example);
359+
}
360+
}
361+
}
362+
}
363+
343364
private static Object getConst(final JsonNode fieldBody) {
344365
return ApiTool.hasConst(fieldBody) ? ApiTool.getConst(fieldBody) : null;
345366
}
@@ -426,11 +447,17 @@ private static List<SchemaFieldObject> processArray(
426447
final Map<String, SchemaObject> compositedSchemas, final Set<String> antiLoopList, final Path baseDir) {
427448
final List<SchemaFieldObject> fieldObjectArrayList = new LinkedList<>();
428449

429-
if (!ApiTool.hasItems(schema)) {
450+
if (!ApiTool.hasItems(schema) || ApiTool.getItems(schema).isBoolean()) {
451+
// No `items` schema, or `items: false` (JSON Schema 2020-12). If the array
452+
// declares positional `prefixItems` (tuple), or nothing typable at all, the
453+
// element type degrades to Object -> List<Object>.
454+
final boolean isTuple = ApiTool.hasPrefixItems(schema);
430455
fieldObjectArrayList.add(SchemaFieldObject
431456
.builder()
432457
.baseName(fieldName)
433-
.dataType(new SchemaFieldObjectType(TypeConstants.OBJECT))
458+
.dataType(isTuple
459+
? SchemaFieldObjectType.fromTypeList(TypeConstants.ARRAY, TypeConstants.OBJECT)
460+
: new SchemaFieldObjectType(TypeConstants.OBJECT))
434461
.build());
435462
} else {
436463
final var items = ApiTool.getItems(schema);
@@ -626,7 +653,9 @@ private static SchemaObject createComposedSchema(
626653
private static void setFieldType(
627654
final SchemaFieldObject field, final JsonNode schemaProperty, final JsonNode schema,
628655
final CommonSpecFile specFile, final String key) {
629-
field.setRequired(ApiTool.hasRequired(schema) && ApiTool.checkIfRequired(schema, key));
656+
// A nullable field (3.0 `nullable: true` or the 3.1 ["T","null"] idiom) must not be
657+
// marked required, otherwise the generated @NotNull would reject a legitimate null value.
658+
field.setRequired(ApiTool.hasRequired(schema) && ApiTool.checkIfRequired(schema, key) && !ApiTool.isNullable(schemaProperty));
630659
if (ApiTool.isArray(schemaProperty)) {
631660
final String typeArray;
632661
if (ApiTool.hasItems(schemaProperty)) {
@@ -888,5 +917,38 @@ private static String getImportClass(final String type) {
888917
return StringUtils.isNotBlank(type) && !TypeConstants.NO_IMPORT_TYPE.contains(type) ? StringUtils.capitalize(type) : "";
889918
}
890919

920+
private static String resolveArrayItemType(final JsonNode schema, final CommonSpecFile specFile) {
921+
final var items = ApiTool.getItems(schema);
922+
if (Objects.nonNull(items) && !items.isBoolean()) {
923+
return ApiTool.hasRef(items) ? MapperUtil.getPojoNameFromRef(items, specFile, null) : ApiTool.getType(items);
924+
}
925+
// `prefixItems` (tuple) or `items: false` -> degrade the element type to Object.
926+
return TypeConstants.OBJECT;
927+
}
928+
929+
private static SchemaFieldObject buildPatternPropertiesField(
930+
final String fieldName, final JsonNode schema, final CommonSpecFile specFile) {
931+
// JSON Schema 2020-12 `patternProperties` maps regex keys to a value schema.
932+
// We model it as Map<String, ValueType> using the first declared pattern's value schema.
933+
final var patternProps = ApiTool.getPatternProperties(schema);
934+
final var valueSchemas = patternProps.elements();
935+
final JsonNode valueSchema = valueSchemas.hasNext() ? valueSchemas.next() : null;
936+
final String valueType;
937+
if (Objects.isNull(valueSchema)) {
938+
valueType = TypeConstants.OBJECT;
939+
} else if (ApiTool.hasRef(valueSchema)) {
940+
valueType = MapperUtil.getPojoNameFromRef(valueSchema, specFile, null);
941+
} else if (isBasicType(valueSchema) && ApiTool.hasType(valueSchema)) {
942+
valueType = MapperUtil.getSimpleType(valueSchema, specFile);
943+
} else {
944+
valueType = TypeConstants.OBJECT;
945+
}
946+
return SchemaFieldObject
947+
.builder()
948+
.baseName(StringUtils.defaultIfBlank(fieldName, ADDITIONAL_PROPERTIES))
949+
.dataType(SchemaFieldObjectType.fromTypeList(TypeConstants.MAP, valueType))
950+
.build();
951+
}
952+
891953

892954
}

‎multiapi-engine/src/main/resources/templates/model/templateSchema.ftlh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -340,7 +340,7 @@ public class ${schema.className} {
340340
}
341341

342342
<#list schema.fieldObjectList as field>
343-
@Schema(name = "${field.baseName?uncap_first}", required = <#if field.required?has_content && field.required == true>true<#else>false</#if>)
343+
@Schema(name = "${field.baseName?uncap_first}", required = <#if field.required?has_content && field.required == true>true<#else>false</#if><#if field.description?has_content>, description = "${field.description?j_string}"</#if><#if field.example?has_content>, example = "${field.example?j_string}"</#if>)
344344
<#if field.dataType.baseType == "array">
345345
public ${field.dataType} get${field.baseName?cap_first}() {
346346
return ${calculateSafeName (field.baseName, ";")}

‎multiapi-engine/src/test/java/com/sngular/api/generator/plugin/openapi/OpenApiGeneratorFixtures.java‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,13 @@ public final class OpenApiGeneratorFixtures {
182182
.clientPackage("com.sngular.multifileplugin.refwithdescription.client")
183183
.modelNameSuffix("DTO").build());
184184

185+
static final List<SpecFile> TEST_OPEN_API_31_COMPLETENESS = List
186+
.of(SpecFile.builder().filePath("openapigenerator/testOpenApi31Completeness/api-test.yml")
187+
.apiPackage("com.sngular.multifileplugin.openapi31completeness")
188+
.modelPackage("com.sngular.multifileplugin.openapi31completeness.model")
189+
.clientPackage("com.sngular.multifileplugin.openapi31completeness.client")
190+
.modelNameSuffix("DTO").build());
191+
185192
static final List<SpecFile> TEST_EXTERNAL_PATH_ITEM_REF_GENERATION = List
186193
.of(SpecFile.builder().filePath("openapigenerator/testExternalPathItemRefsGeneration/api-test.yml")
187194
.apiPackage("com.sngular.multifileplugin.externalpathitemref")
@@ -891,6 +898,25 @@ static Function<Path, Boolean> validateOpenApi31Types() {
891898
DEFAULT_MODEL_API, Collections.emptyList(), null);
892899
}
893900

901+
static Function<Path, Boolean> validateOpenApi31Completeness() {
902+
903+
final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/openapi31completeness";
904+
905+
final String DEFAULT_MODEL_API = "generated/com/sngular/multifileplugin/openapi31completeness/model";
906+
907+
final String COMMON_PATH = "openapigenerator/testOpenApi31Completeness/";
908+
909+
final String ASSETS_PATH = COMMON_PATH + "assets/";
910+
911+
final List<String> expectedTestApiFile = List.of(ASSETS_PATH + "GadgetApi.java");
912+
913+
final List<String> expectedTestApiModelFiles = List.of(ASSETS_PATH + "GadgetDTO.java",
914+
ASSETS_PATH + "PersonDTO.java");
915+
916+
return path -> commonTest(path, expectedTestApiFile, expectedTestApiModelFiles, DEFAULT_TARGET_API,
917+
DEFAULT_MODEL_API, Collections.emptyList(), null);
918+
}
919+
894920
static Function<Path, Boolean> validateRefWithDescription() {
895921

896922
final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/refwithdescription";

‎multiapi-engine/src/test/java/com/sngular/api/generator/plugin/openapi/OpenApiGeneratorTest.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ static Stream<Arguments> fileSpecToProcess() {
8787
OpenApiGeneratorFixtures.validateOpenApi31Types()),
8888
Arguments.of("testRefWithDescription", OpenApiGeneratorFixtures.TEST_REF_WITH_DESCRIPTION,
8989
OpenApiGeneratorFixtures.validateRefWithDescription()),
90+
Arguments.of("testOpenApi31Completeness", OpenApiGeneratorFixtures.TEST_OPEN_API_31_COMPLETENESS,
91+
OpenApiGeneratorFixtures.validateOpenApi31Completeness()),
9092
Arguments.of("testWebhooks", OpenApiGeneratorFixtures.TEST_WEBHOOKS,
9193
OpenApiGeneratorFixtures.validateWebhooks()),
9294
Arguments.of("testOpenApi31Union", OpenApiGeneratorFixtures.TEST_OPEN_API_31_UNION,

‎multiapi-engine/src/test/resources/asyncapigenerator/v2/testCustomValidators/assets/DataDTO.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,22 +98,22 @@ public DataDTO build() {
9898
}
9999
}
100100

101-
@Schema(name = "clientName", required = true)
101+
@Schema(name = "clientName", required = true, description = "Nombre del cliente.")
102102
public String getClientName() {
103103
return clientName;
104104
}
105105

106-
@Schema(name = "flightNumber", required = true)
106+
@Schema(name = "flightNumber", required = true, description = "Número de vuelo.")
107107
public String getFlightNumber() {
108108
return flightNumber;
109109
}
110110

111-
@Schema(name = "clientId", required = true)
111+
@Schema(name = "clientId", required = true, description = "Id del cliente.")
112112
public Integer getClientId() {
113113
return clientId;
114114
}
115115

116-
@Schema(name = "test", required = false)
116+
@Schema(name = "test", required = false, description = "Array para probar anotaciones")
117117
public List<Integer> getTest() {
118118
return test;
119119
}

‎multiapi-engine/src/test/resources/asyncapigenerator/v2/testCustomValidators/assets/StatusMsgDTO.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ public void setStatus(Status status) {
7676
this.status = status;
7777
}
7878

79-
@Schema(name = "clientId", required = false)
79+
@Schema(name = "clientId", required = false, description = "Id del cliente.")
8080
public Integer getClientId() {
8181
return clientId;
8282
}

0 commit comments

Comments
 (0)