Problem when combining @Schema with @JsonBackReference

[dohool]

When designing a model with bidirectional relationships, i am using Jackson's @JsonBackReference annotation to specify the back part, which will be omitted from serialization.

Due to this, it should also be ignored in the openapi documentation.

But using @Schema(hidden = true) in combination with @JsonBackReference does not work. The @Schema(hidden = true) is ignored.

[bnasslahsen]

Hi @dohool,

Please provide the necessary information listed on our contribution guide on the section of Using GitHub Issues:
If you are reporting a bug, please help to speed up problem diagnosis by providing as much information as possible:

• What version of spring-boot you are using?
• What modules and versions of springdoc-openapi are you using?
• What are the actual and the expected result using OpenAPI Description (yml or json)?
• Provide with a sample code (HelloController) or Test that reproduces the problem

This issue will be reopened, once the necessary information are completed. (Please don't create same issue for the same topic)

[dohool]

Spring-Boot-Version: 2.2.1.RELEASE

Springdoc:

<dependency>
        <groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>1.2.29</version>
</dependency>

Model-Class:

    public class UsersDTO {
    private Long personId;

    @JsonManagedReference
    private List<RoleDTO> roles;
}

public class RoleDTO {
    private String role;
    
    @JsonBackReference
    @Schema(hidden = true)
    private UsersDTO user;
}

Expected result (yaml):

    RoleDTO:
      type: object
      properties:
        role:
          type: string

Provided result:

    RoleDTO:
      type: object
      properties:
        role:
          type: string
        user:
          $ref: '#/components/schemas/UsersDTO'

[coryroloff]

I am also seeing this issue in the latest version of springdoc. It looks like the original author provided the requested information, why was the ticket closed? When using @JsonBackReference with @Schema(hidden = true) causes all uses of @Schema to not function.

[jonnydrax]

Spring-Boot-Version: 2.1.10.RELEASE
springdoc-openapi-core: 1.1.44 or 1.1.49

Same issue.

[wtell400]

As described earlier, when trying to hide a field annotated with @JsonBackReference, using @Schema(hidden = true) only on the field, does not work (See EntityA1 in sample). Only annotating the getter does not work either (See ExampleA2 in sample).

@Entity
public class EntityA1
{
    @Id
    private Long id;

    // Only by enabling this AND enabling the annotation on the getter, will the object be hidden.
    @Schema(hidden = true) // enabling only this, does not cause field to be hidden
    @JsonBackReference // disabling this causes field to be hidden
    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "referenced_entity_id")
    private EntityB entityB;

    public Long getId()
    {
        return id;
    }

    //@Schema(hidden = true) // enabling this causes AND enabling on field, causes field to be hidden
    public EntityB getEntityB()
    {
        return entityB;
    }
}

However,

• when removing the @JsonBackReference on the field, seems to hide the field (See EntityA0 in sample).
• when adding the annotation on BOTH the field AND the getter, DOES seems to hide the field (See EntityA3 in sample). This is also the workaround for now.

Expected:

• Adding @Schema(hidden = true) to field annotated with @JsonBackReference should hide field in documentation.

Actual:

• Adding @Schema(hidden = true) to field annotated with @JsonBackReference does not hide field in documentation.

Using springdoc-openapi 1.4.1. See attached project.
springdoc-issue-hidejsonbackreference.zip

[bnasslahsen]

@wtell400,

This is not an issue on springdoc-openapi. We rely on swagger-core official jars.

You are using the combination of @Schema swagger annotation and @JsonBackReference.

• swagger-core effectevely doesn't hide the field when expected.
• You have also mentionned a workaround, but puting the @Schema annotation on the getter.

This is the pure swagger code to reproduce the error:

ResolvedSchema resolvedSchema = ModelConverters.getInstance()
		.resolveAsResolvedSchema(new AnnotatedType(EntityA3.class));
if (resolvedSchema.schema != null) {
	Schema schemaN = resolvedSchema.schema;
	Assert.isNull(schemaN.getProperties().get("entityB"), "Should be hidden");
}

You can submit your request to the swagger-core team for this feature/issue to support about @JsonBackReference compatibility with @Schema annotation:

• https://github.com/swagger-api/swagger-core/issues

[wtell400]

@bnasslahsen,

Thank you for your feedback and taking the time to point out this is not a springdoc issue. I am new to the whole springdoc / swagger world, so I have limited ideas what part are springdoc and what parts are swagger.

As a result of this, I also have no clear idea why adding @JsonBackReference would cause Swagger to stop processing @Schema(hidden = true). Raising an issue with swagger seems to me like I should first better understand swagger-core and whether or not this not working is an expected feature I should have found in the manual, or a bug, or a missing feature. What do you think?

[bnasslahsen]

@wtell400,

Right, you can have a look at the swagger documentation first.
You can run the piece of code above from a simple java main with only the swagger dependencies (no need of springdoc-openapi dependencies to reproduce).
If you are interested to go further, you can debug the swagger code to see the reason why swagger-core doesn't hide the field when expected.