Springdoc-openapi: Ability to define different schemas for the same class

[riimeik]

I've run into a problem trying to reuse the same DTO under different OpenAPI schemas. When I have this hierarchy:

@Data
public class Company {
    @Schema(description = "name of the company")
    private String name;
}

@Data
public class Contract {
    @Schema(description = "unique id")
    private String id;

    @Schema(description = "client company")
    private Company client;

    @Schema(description = "partner company")
    private Company partner;
}}

then Company schema will only be exported once under the name "partner company" in the yml file. This means that the field "client" will have the description "partner company", which makes no sense in this case. I tried giving each field a different name in the Schema annotation, but it seems to be on purpose that you can rewrite a class' schema this way. Why is that?

I'd really like a solution to this problem, because I can't give the client a document with errors like this.

[bnasslahsen]

@riimeik,

You are asking for multiple schema for the same class.
Its technically possible, you can do it programatically using ParameterCustomizer or OperationCustomizer but this seems an overkill solution.

The straight forward solution, is to add a different DTO.

[riimeik]

Considering the existence of schema properties such as nullable and required (which are only relevant to the place of use, not the schema itself), it's a little restrictive that there's a 1-1 relationship between classes and schemas.

I found a hackish solution to this: making the DTO generic, and using different values for the generic parameter for different fields.

[tobre6]

I vote this as well. Type of object doesn't define exact use of it:

@Valid
@Schema(description = "Net weight of the shipment")
private WeightModel netWeight;
@Valid
@Schema(description = "The gross weight of the shipment, in KG-s")
private WeightModel grossWeight;

[bnasslahsen]

@tobre6,

Because we rely on swagger-core project, currently complex (object) payloads are always resolved as a reference to a schema defined in components.

For your problem, you can set up 2 different schemas as follow:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI().components(new Components()
                    .addSchemas("WorkAddressSchema", getSchemaWithDifferentDescription(Address.class, "work Address" ))
                    .addSchemas("HomeAddressSchema", getSchemaWithDifferentDescription(Address.class, "home Address" )));
}

private Schema getSchemaWithDifferentDescription(Class className, String description){
    ResolvedSchema resolvedSchema = ModelConverters.getInstance()
            .resolveAsResolvedSchema(
                    new AnnotatedType(className).resolveAsRef(false));
    return resolvedSchema.schema.description(description);
}

public class PersonDTO {

    @JsonProperty
    private String email;

    @JsonProperty
    private String firstName;

    @JsonProperty
    private String lastName;

    @Schema(ref = "WorkAddressSchema")
    @JsonProperty
    private Address workAddress;

    @Schema(ref = "HomeAddressSchema")
    @JsonProperty
    private Address homeAddress;

}

public class Address {

    @JsonProperty
    private String addressName;

}

This produces, the result you expect: