OAS 3.0 - Use OAS 3.0 annotations instead of old Swagger 1.5.x / OAS 2.x ones (@Api / @ApiXxx) #90
Description
As of now, Swagger Codegen always uses old (1.5.x) Swagger annotations, @ApiModel / @ApiModelProperty to decorate model classes, even if the input specification comes in OAS 3.0.x format. I believe it would make sense to use the Swagger 2.0.x @Schema annotations in this case since it corresponds to OAS 3.0.x specification and has different, richer set of attributes.
It could be done either on advisory level, for example using configOptions (in case of swagger-codegen-maven-plugin):
<configOptions>
<oas3>true</oas3>
</configOptions>
Or, if feasible, could be done automatically in case Swagger Codegen recognizes that specification corresponds to OAS 3.0.x. Here is the example of the model class:
@Schema(description = "...") // Before: @ApiModel
public class Person {
@JsonProperty("email")
private String email = null;
public Person email(String email) {
this.email = email;
return this;
}
@Schema(description = "...", example = "...") // Before: @ApiModelProperty
public String getEmail() {
return email;
}
}
@webron would appreciate your opinion, if the issue makes sense, I will submit the PR for it.
Thank you!