Ability to define different schemas for the same class

[simopahk]

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.

[simopahk]

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:

[HoomanAshaari]

@bnasslahsen

This approach was working for me, until I wanted to define different schemas as responses of an endpoint in @apiresponse (using oneOf field in @Schema which only accepts a list of Classes and I can not pass a list of defined refs in my customOpenAPI bean)
So in this way I think I have no other option than creating one class per schema, while in my case I needed to only define different schemas from one of my classes and then use the refs of those schemas in oneOf/anyOf fields, as possible responses of my endpoints.