Ability to define different schemas for the same class

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]

@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:

[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;