OAS 3.0 - Use OAS 3.0 annotations instead of old Swagger 1.5.x / OAS 2.x ones (@Api / @ApiXxx)

[reta]

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!

[HugoMario]

It totally makes sense to me.

[webron]

@reta Hi! Yup, that makes perfect sense. Of course it would mean using all 2.x annotations and not just @Schema but the idea itself is right.

[reta]

Thank you guys, on it.

[reta]

@webron @HugoMario I started the work on this issue, the scope is larger then I initially expected, I opened #101 (work-in-progress) so you guys could see the progress and guide me through.

As I have got to know the code a bit more, my understanding is that Swagger Codegen Generators module deals with OAS 3.0.x specification only (not the old 2.x one), so I made the changes non-conditional and always use OAS 3.0.x annotations for code generation. Please correct me if I am wrong here.

[HugoMario]

Hello @reta , sorry for delay answer, i wasn't around these last days.

I think your approach is correct and PR LGTM, but i think we need to add an option that let users keep on using the previous annotation. I can help with that.

So the idea is having by default the OAS 3 annotation but leaving an option to anybody that want to keep using the previous one. Let me know if you are done with changes here and i'll file a new ticket for that.

Thanks!

[reta]

Hey @HugoMario,

Thanks for looking! Yeah, it would be a bit of work / conditionals, but makes sense overall, will be working on updating the PR to have both specs supported.

Thanks!

[HugoMario]

Hey @reta
It sounds great, also if you check this guide https://github.com/swagger-api/swagger-codegen/wiki/How-to-add-an-option-to-a-specific-language-or-framework it would give you an idea. I think it can help us with this feature.

[HugoMario]

this has been implemented, so let's close it