How to Configure SmallRye to Avoid Circular References in OpenAPI Documents?

[pv77-2]

Hello,

I'm currently facing an issue with circular references in the OpenAPI document generated by SmallRye. Specifically, I have a component that has a property referencing another component, which in turn has a property referencing back to the first component. This creates a circular reference in the OpenAPI schema.

Is there a way to configure SmallRye to handle this scenario gracefully? I'm open to using annotations, plugin configurations, or any other method that could help resolve or mitigate this issue.

Here's a simplified example to illustrate the problem:

components:
schemas:
ComponentA:
type: object
properties:
refToB:
$ref: '#/components/schemas/ComponentB'
ComponentB:
type: object
properties:
refToA:
$ref: '#/components/schemas/ComponentA'

Any guidance on how to avoid or resolve such circular references would be greatly appreciated.

Thank you in advance for your assistance.

[MikeEdgar]

@pv77-2 are you looking for the referenced schemas to be in-lined directly within the schema?

[pv77-2]

Thank you for your prompt response. While inlining the referenced schemas could potentially solve the issue, I'm concerned about the infinite depth that could arise from circular references. Unless there's a way to limit the depth of the inlining, I don't think this would be a viable solution for my case.

Is there another way to handle or break circular references in the generated OpenAPI document?

[MikeEdgar]

You could implement an OASFilter and change the schemas after they are generated. Are the classes below an accurate representation of your model? It may be the case that the circular refs are fine. Another option if you don't want one of them to be present would be to use @Schema(hidden = true) on the field you wish to hide.

@Schema(name = "ComponentA")
class ComponentA {
    ComponentB refToB;
}

@Schema(name = "ComponentB")
class ComponentB {
    ComponentA refToA;
}

[codespearhead]

@pv77-2 Does the above suggestion answer your question? If so, can you mark this discussion as answered?