Skip to content

Conversation

@huisoo
Copy link

@huisoo huisoo commented Jan 11, 2026

Issue Description

This PR resolves Issue #3161 where the _links field was incorrectly duplicated in child schemas when using allOf composition with RepresentationModel.

Problem:

  • Child schemas extending a parent that extends RepresentationModel had duplicate _links fields
  • allOf composition automatically inherits parent properties, so _links shouldn't be redefined
  • Violates OpenAPI specification and confuses API consumers

Reproduction:
See springdoc-issue-3161-reproduction for a detailed demonstration of this bug.

Solution:
Modified PolymorphicModelConverter to remove inherited _links from child schema properties when using allOf composition.


Changes Made

Core Changes:

  • PolymorphicModelConverter.java: Remove _links field from child schemas in allOf composition

Test Coverage:

  • SpringDocApp11Test (OpenAPI 3.0.1): 5 test methods validating the fix
  • SpringDocApp13Test (OpenAPI 3.1.0): Compatibility validation
  • Test Models & Resources: DTOs, Controllers, and expected JSON specs

Test Methods:

  • testApp(): Full OpenAPI JSON validation
  • testTestDtoHasHateoasLinks(): Parent has _links
  • testExtendedTestDtoAllOfInheritance(): Proper allOf structure
  • testExtendedTestDtoNoLinksInOwnProperties(): No duplicate _linksIssue Wrong HAL _links are generated in sub type of a schema #3161 core validation
  • testExtendedTestDtoHasOwnProperties(): Child properties preserved

Before & After

Before (Bug):

"ExtendedTestDto": {
  "allOf": [
    {"$ref": "#/components/schemas/TestDto"},
    {
      "properties": {
        "otherField": {...},
        "_links": {...}  // ❌ Duplicate
      }
    }
  ]
}

After (Fixed):

"ExtendedTestDto": {
  "allOf": [
    {"$ref": "#/components/schemas/TestDto"},
    {
      "properties": {
        "otherField": {...}  // ✅ No duplicate
      }
    }
  ]
}

Testing

  • ✅ All tests passing (10 test methods)
  • ✅ Tested across both OpenAPI 3.0.1 and 3.1.0 spec versions
  • ✅ Compatible with springdoc-openapi 2.8.14+
  • ✅ Backward compatible
  • ✅ No breaking changes

Fixes #3161

Test Result ( open api version 3.0.1 )

image

Test Result ( open api version 3.1.0 )

image

Additional Improvements

While fixing the allOf issue, a defensive enhancement was added for oneOf compositions:

  • Apply the same _links inheritance principle to oneOf schemas
  • Prevent potential duplication if inline schemas are used in oneOf
  • No impact on typical oneOf usage (usually only contains $ref)

This is a preventive measure to maintain consistency across all composition types. Primary validation remains focused on the allOf issue reported in #3161.

- Remove _links field duplication in child schemas extending RepresentationModel
- Preserve inherited _links through allOf composition pattern
- Add comprehensive test coverage for OpenAPI 3.0.1 and 3.1.0

Fixes springdoc#3161
}

// ... rest of existing code ...
return schema;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it intentional here to completely remove result as data that is used? Previously that object was constructed and returned, but now it does not seem to serve any purpose at all and is instead completely ignored?

Copy link
Author

@huisoo huisoo Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review.

I’ve addressed the feedback by ensuring that the constructed polymorphic ComposedSchema (result) is properly returned.

While doing so, I also extended the defensive _links cleanup logic to oneOf compositions, matching the behavior already in place for allOf.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am only a project contributor, and not a maintainer, so I cannot approve any PR:s. It is the maintainer that approves and merges the suggested changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Wrong HAL _links are generated in sub type of a schema

2 participants