fix(InlineModelResolver): prevent numbered duplicate models from multi-file OAS 3.1 specs (#23856)

* fix(InlineModelResolver): prevent numbered duplicate models from multi-file OAS 3.1 specs

When a multi-file OpenAPI 3.1 spec uses external $ref schemas (e.g. JSON
Schema files), the swagger-parser resolves them into shared, mutable Java
Schema objects.  Between processing passes the parser mutates these shared
objects in several ways that cause matchGenerated() to produce false misses,
which in turn cause numbered duplicate component schemas to be emitted:

  * Strips 'type' annotations (e.g. type:"string") from property sub-schemas
  * Strips 'description' text from shared property sub-schemas
  * Leaves 'example' set on one $ref usage but absent on another (OAS 3.1
    allows 'example' as a $ref sibling)
  * Stores an explicit 'default: null' in YAML as a Jackson NullNode (a
    non-null Java object serialised as '"default":null'), while a property
    with no 'default' keyword at all produces a Java null that the NON_NULL
    mapper omits — two representations of "no default" that compared unequal

These mutations caused matchGenerated() to fail its structural comparison,
creating e.g. Flow_Segment_1 alongside Flow_Segment for the TAMS-BBC spec.

Changes:

1. IgnoreVolatileFieldsMixIn — extends @JsonIgnoreProperties to strip
   'description', 'type', and 'example' at every level of the schema graph
   when computing the structural signature.

2. computeStructuralSignature() — replaces direct structuralMapper calls.
   After mixin-based serialisation it parses the JSON tree and removes any
   "default":null (NullNode) entries before returning the key, making an
   explicit null default compare equal to an absent default while preserving
   real non-null defaults (e.g. default:"available").

3. Pre-populate generatedSignature / generatedStructuralSignature with
   titled schemas already in components/schemas before flattening begins, so
   that subsequent inline schemas matching existing ones reuse the existing
   name rather than receiving a numbered suffix.  Only titled schemas are
   pre-populated: a schema identified only by its YAML key in
   components/schemas has no inherent identity — two anonymous schemas that
   share the same properties may be intentionally distinct.

4. deduplicateComponents() — post-flatten safety-net pass that scans
   components/schemas for titled schemas whose structural signatures match,
   removes the numbered duplicate (e.g. Flow_Segment_1), and rewrites every
   $ref throughout paths, webhooks, and component schemas to point to the
   canonical name.

5. Tests — two new regression tests in InlineModelResolverTest plus a set
   of multi-file YAML fixtures in src/test/resources/3_0/inline-model-
   resolver-dedup/ that reproduce the parser-mutation scenario:
   * resolveInlineModelDeduplicatesWhenParserMutatesPropertyTypes — verifies
     the structural-hash fallback fires when the parser strips 'type' from
     string properties of a shared Schema object
   * deduplicateComponentsRemovesNumberedDuplicateOfTitledSchemaAndRewritesRefs
     — verifies the post-flatten dedup removes the numbered copy and
     rewrites all $refs in path responses

* chore(samples): regenerate affected samples after InlineModelResolver deduplication fixes

Regenerated all samples via bin/generate-samples.sh (maven:3.9-eclipse-temurin-11,
matching CI JDK version) to reflect the corrected InlineModelResolver behaviour
introduced in the two preceding commits.

Affected generators and the root cause for each change:

csharp-generichost (FormModels, net4.7/4.8/8/9/10)
  TestEnumParametersEnumHeaderStringParameter removed; enum_header_string and
  enum_query_string parameters now typed as TestEnumParametersRequestEnumFormString.
  Reason: the header-string and query-string inline enums are structurally identical
  to the form-string enum; the structural deduplication map (ignoring description
  fields) now correctly merges them instead of generating a numbered duplicate.

python / python-aiohttp / python-httpx / python-lazyImports /
python-pydantic-v1 / python-pydantic-v1-aiohttp
  UploadFileWithAdditionalPropertiesRequestObject removed; the upload_file_with_
  additional_properties endpoint's object parameter is now typed as
  TestObjectForMultipartRequestsRequestMarker.
  Reason: same structural-deduplication fix — the inline request schema is
  structurally identical to the pre-existing TestObjectForMultipartRequestsRequestMarker
  component and is now correctly reused rather than generating a new model class.

php-laravel
  FakeApiInterface / FakeController updated to reflect the merged type names
  for both enum and upload-object parameters.

rust-server / rust-server-deprecated (petstore-with-fake-endpoints-models-for-testing)
  TestEnumParametersEnumHeaderStringParameter model and all usages replaced with
  TestEnumParametersRequestEnumFormString across models.rs, cli.rs, client/mod.rs,
  server/mod.rs, and example files. openapi.yaml inlined schemas updated accordingly.

No functional change — the generated clients/servers remain equivalent; only the
model class names for previously-duplicate anonymous schemas have been normalised.

* fix(samples): resolve CI failures caused by incomplete sample regeneration after InlineModelResolver deduplication

The previous sample regeneration (1214fd1) after the InlineModelResolver
deduplication fix left two sets of samples in an inconsistent state:

C# GenericHost FormModels (net8, net9, net10, net4.7, net4.8):
- TestEnumParametersEnumHeaderStringParameter was correctly identified as
  a structural duplicate of TestEnumParametersRequestEnumFormString and
  deduplicated, but the model files (.cs, .md, test .cs) were not deleted
  from the committed samples. The API implementation was updated to use
  TestEnumParametersRequestEnumFormString, but FakeApiTests.cs still
  referenced the deleted type, causing CS1503 compile errors.
- Fix: delete the three orphaned TestEnumParametersEnumHeaderStringParameter
  files per variant and update FakeApiTests.cs to use
  TestEnumParametersRequestEnumFormString for enumHeaderString and
  enumQueryString parameters.

Python petstore samples (python, python-aiohttp, python-httpx,
python-lazyImports, python-pydantic-v1, python-pydantic-v1-aiohttp):
- UploadFileWithAdditionalPropertiesRequestObject was correctly deduplicated
  to TestObjectForMultipartRequestsRequestMarker (structurally identical:
  both have name: Optional[str] with additional properties). The generated
  API method upload_file_with_additional_properties now uses
  TestObjectForMultipartRequestsRequestMarker as the object parameter type,
  but the hand-written test_rest.py in each variant still instantiated the
  old UploadFileWithAdditionalPropertiesRequestObject, causing AttributeError
  at runtime.
- Fix: update test_rest.py in all six variants to use
  TestObjectForMultipartRequestsRequestMarker instead.

All fixes verified locally via Docker (Python 3.12, poetry run pytest).

Author: Shaun-3adesign

modules/openapi-generator/src/main/java/org/openapitools/codegen/InlineModelResolver.java

@@ -22,6 +22,7 @@
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.Operation;
 import io.swagger.v3.oas.models.PathItem;
+import io.swagger.v3.oas.models.Paths;
 import io.swagger.v3.oas.models.media.*;
 import io.swagger.v3.oas.models.parameters.Parameter;
 import io.swagger.v3.oas.models.parameters.RequestBody;
@@ -175,6 +176,125 @@ public void resolveInlineModel2EqualInnerModels() {
         assertNull(duplicateAddress);
     }
 
+    @Test
+    public void resolveInlineModelDeduplicatesAgainstExistingComponentSchema() {
+        // When a pre-existing components/schemas entry has the same title and content as an
+        // inline schema encountered during flattening, the inline schema should reuse the
+        // pre-existing name rather than being registered as a numbered variant (e.g. Foo_1).
+        // Regression test for: external $ref chains producing ContainerMapping + ContainerMapping_1.
+        OpenAPI openapi = new OpenAPI();
+        openapi.setComponents(new Components());
+
+        // Pre-existing named schema registered directly in components
+        openapi.getComponents().addSchemas("ContainerMapping", new ObjectSchema()
+                .title("ContainerMapping")
+                .description("Describes the mapping of essence from a container")
+                .addProperty("track_index", new IntegerSchema()));
+
+        // Schema whose inline property content is identical to the pre-existing ContainerMapping
+        openapi.getComponents().addSchemas("FlowCore", new ObjectSchema()
+                .name("FlowCore")
+                .addProperty("container_mapping", new ObjectSchema()
+                        .title("ContainerMapping")
+                        .description("Describes the mapping of essence from a container")
+                        .addProperty("track_index", new IntegerSchema())));
+
+        new InlineModelResolver().flatten(openapi);
+
+        // The pre-existing entry must still exist
+        assertNotNull(openapi.getComponents().getSchemas().get("ContainerMapping"));
+        // No numbered duplicate should have been created
+        assertNull(openapi.getComponents().getSchemas().get("ContainerMapping_1"));
+    }
+
+    @Test
+    public void resolveInlineModelDeduplicatesAcrossExternalRefChains() {
+        // Regression test: same external schema referenced from two schemas (one via plain $ref,
+        // one via $ref + sibling description as allowed in OpenAPI 3.1) must not produce a
+        // duplicate numbered model (Container_Mapping_1).
+        ParseOptions parseOptions = new ParseOptions();
+        parseOptions.setResolve(true);
+        parseOptions.setResolveResponses(true);
+        OpenAPI openAPI = new OpenAPIParser().readLocation(
+                "src/test/resources/3_0/inline-model-resolver-dedup/root.yaml",
+                null, parseOptions).getOpenAPI();
+        new InlineModelResolver().flatten(openAPI);
+
+        Map<String, Schema> schemas = openAPI.getComponents().getSchemas();
+        assertNotNull(schemas.get("Container_Mapping"));
+        assertNull("Duplicate Container_Mapping_1 must not exist", schemas.get("Container_Mapping_1"));
+    }
+
+    @Test
+    public void resolveInlineModelDeduplicatesWhenParserMutatesPropertyDescriptions() {
+        // Regression test: when the Swagger Parser shares and mutates resolved Schema objects
+        // (e.g. a shared uuid.json resolved Schema has its description overwritten by whichever
+        // property referencing it was last processed), two Schema objects from the same external
+        // file may end up with different serialised JSON despite being structurally identical.
+        // The structural-hash fallback in matchGenerated() (serialised without any 'description'
+        // fields at any level) must still deduplicate them rather than creating a numbered variant.
+        OpenAPI openapi = new OpenAPI();
+        openapi.setComponents(new Components());
+        openapi.setPaths(new Paths());
+
+        // Schema A: properties have "correct" descriptions (as the file author wrote them)
+        Schema widgetA = new ObjectSchema()
+                .title("Widget")
+                .description("A reusable widget")
+                .addProperty("id", new StringSchema().description("Widget identifier"))
+                .addProperty("name", new StringSchema().description("Widget name"));
+
+        // Schema B: same title/description/property-names, but 'id' has a DIFFERENT description
+        // (simulating what the Swagger Parser does when it shares and mutates a resolved sub-schema)
+        Schema widgetB = new ObjectSchema()
+                .title("Widget")
+                .description("A reusable widget")
+                .addProperty("id", new StringSchema().description("MUTATED description from another schema"))
+                .addProperty("name", new StringSchema().description("Widget name"));
+
+        ApiResponse responseA = new ApiResponse()
+                .description("OK")
+                .content(new Content().addMediaType("application/json",
+                        new MediaType().schema(widgetA)));
+        ApiResponse responseB = new ApiResponse()
+                .description("OK")
+                .content(new Content().addMediaType("application/json",
+                        new MediaType().schema(widgetB)));
+
+        openapi.getPaths()
+                .addPathItem("/a", new PathItem().get(
+                        new Operation().operationId("getA").responses(new ApiResponses().addApiResponse("200", responseA))))
+                .addPathItem("/b", new PathItem().get(
+                        new Operation().operationId("getB").responses(new ApiResponses().addApiResponse("200", responseB))));
+
+        new InlineModelResolver().flatten(openapi);
+
+        Map<String, Schema> schemas = openapi.getComponents().getSchemas();
+        assertNotNull("Widget schema must exist", schemas.get("Widget"));
+        assertNull("Duplicate Widget_1 must not exist — shape-fingerprint dedup must fire", schemas.get("Widget_1"));
+    }
+
+    @Test
+    public void resolveInlineModelDeduplicatesMultipleRefsToSameExternalFile() {
+        // Regression test: when the same external schema file is referenced from three separate
+        // paths (simulating DeletionRequest appearing multiple times in the TAMS spec), the parser
+        // may share the same Java Schema object across all three references. After the first
+        // processing mutates the object (inline sub-schemas replaced with $refs), subsequent
+        // encounters hash differently. The identity-based fast path in matchGenerated() must
+        // recognise the same object reference and avoid registering a numbered duplicate.
+        ParseOptions parseOptions = new ParseOptions();
+        parseOptions.setResolve(true);
+        parseOptions.setResolveResponses(true);
+        OpenAPI openAPI = new OpenAPIParser().readLocation(
+                "src/test/resources/3_0/inline-model-resolver-dedup/root.yaml",
+                null, parseOptions).getOpenAPI();
+        new InlineModelResolver().flatten(openAPI);
+
+        Map<String, Schema> schemas = openAPI.getComponents().getSchemas();
+        assertNotNull(schemas.get("Deletion_Request"));
+        assertNull("Duplicate Deletion_Request_1 must not exist", schemas.get("Deletion_Request_1"));
+    }
+
     @Test
     public void resolveInlineModel2DifferentInnerModelsWithSameTitle() {
         OpenAPI openapi = new OpenAPI();
@@ -1205,4 +1325,111 @@ public void doNotWrapSingleAllOfRefs() {
         assertNotNull(allOfRefWithDescriptionAndReadonly.getAllOf());
         assertEquals(numberRangeRef, ((Schema) allOfRefWithDescriptionAndReadonly.getAllOf().get(0)).get$ref());
     }
+
+    @Test
+    public void resolveInlineModelDeduplicatesWhenParserMutatesPropertyTypes() {
+        // Regression test: the Swagger Parser shares a single resolved Schema object across all
+        // usages of an external type (e.g. storage-backend.json) and strips the 'type' field
+        // from its properties between processing passes.  The first usage sees properties with
+        // type:"string"; the second usage sees the same object but with type stripped to null.
+        // IgnoreVolatileFieldsMixIn now strips 'type' in addition to 'description', so the
+        // structural-hash fallback in matchGenerated() must still unify them rather than creating
+        // a numbered variant.
+        OpenAPI openapi = new OpenAPI();
+        openapi.setComponents(new Components());
+        openapi.setPaths(new Paths());
+
+        // First inline schema: properties carry explicit type annotations (as delivered by the
+        // parser on first encounter of the shared external schema object)
+        StringSchema prop1First = new StringSchema();
+        prop1First.setDescription("The store type");
+        StringSchema prop2First = new StringSchema();
+        prop2First.setDescription("The provider");
+        Schema schemaFirstPass = new ObjectSchema()
+                .title("StorageBackend")
+                .description("A storage backend")
+                .addProperty("store_type", prop1First)
+                .addProperty("provider",   prop2First);
+
+        // Second inline schema: same structure but 'type' has been stripped from properties,
+        // simulating the Swagger Parser mutating the shared resolved Schema object between passes.
+        StringSchema prop1Second = new StringSchema();
+        prop1Second.setType(null);   // simulate parser stripping the type field
+        prop1Second.setDescription("The store type");
+        StringSchema prop2Second = new StringSchema();
+        prop2Second.setType(null);
+        prop2Second.setDescription("The provider");
+        Schema schemaSecondPass = new ObjectSchema()
+                .title("StorageBackend")
+                .description("A storage backend")
+                .addProperty("store_type", prop1Second)
+                .addProperty("provider",   prop2Second);
+
+        openapi.getPaths()
+                .addPathItem("/a", new PathItem().get(new Operation().operationId("getA")
+                        .responses(new ApiResponses().addApiResponse("200", new ApiResponse()
+                                .description("OK")
+                                .content(new Content().addMediaType("application/json",
+                                        new MediaType().schema(schemaFirstPass)))))))
+                .addPathItem("/b", new PathItem().get(new Operation().operationId("getB")
+                        .responses(new ApiResponses().addApiResponse("200", new ApiResponse()
+                                .description("OK")
+                                .content(new Content().addMediaType("application/json",
+                                        new MediaType().schema(schemaSecondPass)))))));
+
+        new InlineModelResolver().flatten(openapi);
+
+        Map<String, Schema> schemas = openapi.getComponents().getSchemas();
+        assertNotNull("StorageBackend schema must exist", schemas.get("StorageBackend"));
+        assertNull("Duplicate StorageBackend_1 must not exist — type-stripped structural match must fire",
+                schemas.get("StorageBackend_1"));
+    }
+
+    @Test
+    public void deduplicateComponentsRemovesNumberedDuplicateOfTitledSchemaAndRewritesRefs() {
+        // Regression test: when flattening creates a numbered duplicate of a titled component
+        // (e.g. FlowSegment_1 alongside FlowSegment) because matchGenerated() missed the match
+        // due to T0-vs-T1 pre-populate timing, deduplicateComponents() must remove the duplicate
+        // and rewrite all $refs to it throughout the spec so the generated code only contains one
+        // class.
+        OpenAPI openapi = new OpenAPI();
+        openapi.setComponents(new Components());
+        openapi.setPaths(new Paths());
+
+        Schema canonical = new ObjectSchema()
+                .title("Widget")
+                .description("A widget")
+                .addProperty("name", new StringSchema());
+
+        // Duplicate: same title and structure — simulates what flatten() can produce when the
+        // pre-populate T0 signature no longer matches the T1 form of the same inline schema.
+        Schema duplicate = new ObjectSchema()
+                .title("Widget")
+                .description("A widget")
+                .addProperty("name", new StringSchema());
+
+        openapi.getComponents().addSchemas("Widget",   canonical);
+        openapi.getComponents().addSchemas("Widget_1", duplicate);
+
+        // Path whose response references the numbered duplicate
+        openapi.getPaths().addPathItem("/widgets", new PathItem().get(
+                new Operation().operationId("getWidget").responses(
+                        new ApiResponses().addApiResponse("200", new ApiResponse()
+                                .description("OK")
+                                .content(new Content().addMediaType("application/json",
+                                        new MediaType().schema(new Schema<>()
+                                                .$ref("#/components/schemas/Widget_1"))))))));
+
+        new InlineModelResolver().flatten(openapi);
+
+        Map<String, Schema> schemas = openapi.getComponents().getSchemas();
+        assertNotNull("Canonical Widget must survive deduplication", schemas.get("Widget"));
+        assertNull("Duplicate Widget_1 must be removed by deduplicateComponents()", schemas.get("Widget_1"));
+
+        // The $ref in the path response must have been rewritten to the canonical name
+        Schema responseSchema = openapi.getPaths().get("/widgets").getGet()
+                .getResponses().get("200").getContent().get("application/json").getSchema();
+        assertEquals("$ref must be rewritten from Widget_1 to Widget",
+                "#/components/schemas/Widget", responseSchema.get$ref());
+    }
 }

modules/openapi-generator/src/test/java/org/openapitools/codegen/InlineModelResolverTest.java

@@ -0,0 +1,6 @@
+title: Collection Item
+description: An item in a collection
+type: object
+properties:
+  id:
+    type: string

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/collection-item.yaml

@@ -0,0 +1,8 @@
+title: Container Mapping
+description: Defines the location of Flow essence data in a container track
+type: object
+properties:
+  track_index:
+    description: A zero-based track index
+    type: integer
+    minimum: 0

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/container-mapping.yaml

@@ -0,0 +1,16 @@
+title: Deletion Request
+description: Describes an ongoing deletion request
+type: object
+required:
+  - id
+  - status
+properties:
+  id:
+    type: string
+    format: uuid
+  status:
+    type: string
+    enum: [created, done]
+  error:
+    description: Provides more information for the error status
+    $ref: error.yaml

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/deletion-request.yaml

@@ -0,0 +1,8 @@
+title: Error
+description: An API error response
+type: object
+properties:
+  code:
+    type: integer
+  message:
+    type: string

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/error.yaml

@@ -0,0 +1,13 @@
+title: Flow Collection
+description: A collection of flows
+type: array
+items:
+  type: object
+  title: Flow Collection Item
+  allOf:
+    - $ref: collection-item.yaml
+    - type: object
+      properties:
+        container_mapping:
+          description: Describes the mapping of the Flow essence from this collection's container
+          $ref: container-mapping.yaml

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/flow-collection.yaml

@@ -0,0 +1,8 @@
+title: Flow Core
+description: Core flow properties
+type: object
+properties:
+  id:
+    type: string
+  container_mapping:
+    $ref: container-mapping.yaml

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/flow-core.yaml

@@ -0,0 +1,9 @@
+title: Video Flow
+description: A video flow
+type: object
+allOf:
+  - $ref: flow-core.yaml
+  - type: object
+    properties:
+      format:
+        type: string

modules/openapi-generator/src/test/resources/3_0/inline-model-resolver-dedup/flow-video.yaml

@@ -0,0 +1,62 @@
+openapi: "3.1.0"
+info:
+  title: Dedup Test
+  version: "1.0"
+paths:
+  /flows:
+    get:
+      operationId: getFlows
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: flow-video.yaml
+  /flow-collections:
+    get:
+      operationId: getFlowCollections
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: flow-collection.yaml
+  /deletions/{id}:
+    get:
+      operationId: getDeletion
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: deletion-request.yaml
+  /deletions/{id}/status:
+    get:
+      operationId: getDeletionStatus
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: deletion-request.yaml
+  /deletions:
+    get:
+      operationId: listDeletions
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: deletion-request.yaml
+components: {}