diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java index f944c5d9afc2..b67f30de0e13 100644 --- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java +++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java @@ -2681,7 +2681,9 @@ private static void restoreNullableInList(List original, List cl * @return The simplified schema */ public static Schema simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(OpenAPI openAPI, Schema schema, List subSchemas) { - if (subSchemas.removeIf(subSchema -> isNullTypeSchema(openAPI, subSchema))) { + boolean openapi31 = openAPI != null && SpecVersion.V31.equals(openAPI.getSpecVersion()); + boolean nullSubSchemaRemoved = subSchemas.removeIf(subSchema -> isNullTypeSchema(openAPI, subSchema)); + if (nullSubSchemaRemoved) { schema.setNullable(true); } @@ -2691,11 +2693,17 @@ public static Schema simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(OpenAPI openA // The parser may reuse a $ref schema instance in multiple locations. Clone the // remaining $ref before applying parent metadata so those locations stay isolated. if (subSchema.get$ref() != null) { - subSchema = cloneSchema(subSchema, - openAPI != null && SpecVersion.V31.equals(openAPI.getSpecVersion())); - } - // Preserve parent-level docs when nullable anyOf/oneOf collapses to a single child schema. - if (subSchema.getDescription() == null && schema.getDescription() != null) { + subSchema = cloneSchema(subSchema, openapi31); + } + // Preserve parent-level docs when anyOf/oneOf collapses to a single child schema. + // Exception: a non-nullable collapse to a $ref is a pure alias. Adding the parent + // description there would turn the $ref into a schema with sibling metadata and + // prevent the alias from being removed, so the description is dropped in that case. + boolean transferDescriptionToChild = subSchema.getDescription() == null && schema.getDescription() != null; + boolean collapsesToRefAlias = subSchema.get$ref() != null + && !nullSubSchemaRemoved + && !Boolean.TRUE.equals(schema.getNullable()); + if (transferDescriptionToChild && !collapsesToRefAlias) { subSchema.setDescription(schema.getDescription()); } if (Boolean.TRUE.equals(schema.getNullable())) { // retain nullable setting diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java index 144bb6927b96..ec382d0bca19 100644 --- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java +++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java @@ -9502,6 +9502,19 @@ void oneOf_issue_14769() throws IOException { .extendsClass("VehicleDto"); } + @Test + void oneOf_single_alternative_with_description_is_removed_with_default_normalization() throws IOException { + Map files = generateFromContract("src/test/resources/3_0/oneOf_single_alternative_normalization.yaml", SPRING_BOOT, + Map.of(GENERATE_MODEL_DOCS, false, GENERATE_APIS, false, INTERFACE_ONLY, true)); + + assertThat(files).doesNotContainKey("Shape.java"); + assertThat(files).containsKeys("Circle.java"); + JavaFileAssert.assertThat(files.get("Circle.java")).fileContains("class Circle", "kind", "radius") + .fileDoesNotContain("description = \"A shape to draw.\""); + assertThat(files).containsKeys("NullableShape.java"); + JavaFileAssert.assertThat(files.get("NullableShape.java")).fileContains("description = \"A shape to draw.\""); + } + @Test void disableDiscriminatorJsonIgnorePropertiesIsTrueThenJsonIgnorePropertiesShouldBeNotAdded() throws IOException { final Map files = generateFromContract("src/test/resources/3_0/java/issue12777.yaml", SPRING_BOOT, diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java index 6e33d15023d6..c71e73ea323a 100644 --- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java +++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java @@ -700,32 +700,92 @@ public void simplifyAnyOfWithOnlyOneNonNullSubSchemaKeepsReadOnlyWriteOnlyAttrib public void simplifyOneOfAnyOfWithOnlyOneNonNullSubSchemaKeepsParentDescription() { OpenAPI openAPI = new OpenAPI(); - Schema anyOfParent = new Schema().description("Access token"); - anyOfParent.setAnyOf(new ArrayList<>(Arrays.asList( + Schema anyOfParent = anyOfSchema( + "Access token", new StringSchema(), new Schema<>().type("null") - ))); + ); Schema anyOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, anyOfParent, anyOfParent.getAnyOf()); assertEquals(anyOfSchema.getDescription(), "Access token"); - Schema oneOfParent = new Schema().description("Expires at"); - oneOfParent.setOneOf(new ArrayList<>(Arrays.asList( + Schema oneOfParent = oneOfSchema( + "Expires at", new IntegerSchema(), new Schema<>().type("null") - ))); + ); Schema oneOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, oneOfParent, oneOfParent.getOneOf()); assertEquals(oneOfSchema.getDescription(), "Expires at"); - Schema anyOfParentWithChildDescription = new Schema().description("Parent description"); - anyOfParentWithChildDescription.setAnyOf(new ArrayList<>(Arrays.asList( + Schema anyOfParentWithChildDescription = anyOfSchema( + "Parent description", new StringSchema().description("Child description"), new Schema<>().type("null") - ))); + ); Schema anyOfSchemaWithChildDescription = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema( openAPI, anyOfParentWithChildDescription, anyOfParentWithChildDescription.getAnyOf()); assertEquals(anyOfSchemaWithChildDescription.getDescription(), "Child description"); + + Schema oneOfParentWithChildDescription = oneOfSchema( + "Parent description", + new StringSchema().description("Child description"), + new Schema<>().type("null") + ); + Schema oneOfSchemaWithChildDescription = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema( + openAPI, + oneOfParentWithChildDescription, + oneOfParentWithChildDescription.getOneOf()); + assertEquals(oneOfSchemaWithChildDescription.getDescription(), "Child description"); + } + + @Test + public void simplifySingleRefOneOfAnyOfDropsParentDescriptionToKeepAlias() { + OpenAPI openAPI = new OpenAPI(); + + Schema refSchema = new Schema().$ref("#/components/schemas/IntegerRef"); + + Schema oneOfParent = oneOfSchema("Expires at", refSchema); + Schema oneOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, oneOfParent, oneOfParent.getOneOf()); + + assertNull(oneOfSchema.getDescription()); + assertEquals(oneOfSchema.get$ref(), "#/components/schemas/IntegerRef"); + + Schema anyOfParent = anyOfSchema("Expires at", refSchema); + Schema anyOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, anyOfParent, anyOfParent.getAnyOf()); + + assertNull(anyOfSchema.getDescription()); + assertEquals(anyOfSchema.get$ref(), "#/components/schemas/IntegerRef"); + + Schema nullableOneOfParent = oneOfSchema("Expires at", refSchema); + nullableOneOfParent.setNullable(true); + Schema nullableOneOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, nullableOneOfParent, nullableOneOfParent.getOneOf()); + + assertEquals(nullableOneOfSchema.getDescription(), "Expires at"); + assertEquals(nullableOneOfSchema.get$ref(), "#/components/schemas/IntegerRef"); + + Schema nullableAnyOfParent = anyOfSchema("Expires at", refSchema); + nullableAnyOfParent.setNullable(true); + Schema nullableAnyOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, nullableAnyOfParent, nullableAnyOfParent.getAnyOf()); + + assertEquals(nullableAnyOfSchema.getDescription(), "Expires at"); + assertEquals(nullableAnyOfSchema.get$ref(), "#/components/schemas/IntegerRef"); + } + + @Test + public void simplifySingleInlineOneOfAnyOfKeepsParentDescription() { + OpenAPI openAPI = new OpenAPI(); + + Schema oneOfParent = oneOfSchema("Expires at"); + Schema oneOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, oneOfParent, oneOfParent.getOneOf()); + + assertEquals(oneOfSchema.getDescription(), "Expires at"); + assertNull(oneOfSchema.get$ref()); + + Schema anyOfParent = anyOfSchema("Expires at"); + Schema anyOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, anyOfParent, anyOfParent.getAnyOf()); + + assertEquals(anyOfSchema.getDescription(), "Expires at"); } @Test @@ -1427,4 +1487,28 @@ private static Schema nullableStringSchema() { return schema; } + private static Schema oneOfSchema(String description) { + return oneOfSchema(description, new IntegerSchema()); + } + + private static Schema oneOfSchema(String description, Schema... alternatives) { + Schema oneOfSchema = new Schema<>().description(description); + oneOfSchema.setOneOf(new ArrayList<>(Arrays.asList( + alternatives + ))); + return oneOfSchema; + } + + private static Schema anyOfSchema(String description) { + return anyOfSchema(description, new IntegerSchema()); + } + + private static Schema anyOfSchema(String description, Schema... alternatives) { + Schema anyOfSchema = new Schema<>().description(description); + anyOfSchema.setAnyOf(new ArrayList<>(Arrays.asList( + alternatives + ))); + return anyOfSchema; + } + } diff --git a/modules/openapi-generator/src/test/resources/3_0/oneOf_single_alternative_normalization.yaml b/modules/openapi-generator/src/test/resources/3_0/oneOf_single_alternative_normalization.yaml new file mode 100644 index 000000000000..c094f9058de3 --- /dev/null +++ b/modules/openapi-generator/src/test/resources/3_0/oneOf_single_alternative_normalization.yaml @@ -0,0 +1,41 @@ +openapi: 3.0.0 +info: + title: Shape API + version: "1" +paths: + /shapes: + post: + operationId: createShape + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Shape" + responses: + "201": + description: Created +components: + schemas: + # The default normalization behavior for a oneOf schema with a single alternative is to collapse the oneOf and use the child schema directly. + # This is because the oneOf can be considered redundant when there is only one option. + # The description is ignored since we want to ensure that the collapsed schema is treated as an alias and removed. + Shape: + description: A shape to draw. + oneOf: + - $ref: "#/components/schemas/Circle" + NullableShape: + description: A shape to draw. + oneOf: + - $ref: "#/components/schemas/Circle" + - type: "null" + Circle: + type: object + required: + - kind + - radius + properties: + kind: + type: string + radius: + type: number +