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

reta · 2018-06-17T21:53:45Z

As of now, Swagger Codegen always uses old (1.5.x) Swagger annotations, @Api / @ApiModel / @ApiModelProperty / ... to decorate model classes, APIs, operations, ... even if the input specification comes in OAS 3.0.x format. It would make sense to use the Swagger 2.0.x annotations in this case since it corresponds to OAS 3.0.x specification and has different, richer set of attributes.

Issue:

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

Server / client stubs updated:

As now Springfox (the Swagger/OpenAPI integration for Spring / Spring Boot ) does not support OpenAPI (Swagger 2.0.x), leaving it untouched.

Added new command-line argument to preserve the usages of the older OpenAPI 2.0 (Swagger 1.5.x) annotations and specification.

From the command line:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate 
    -l java  
    -i http://petstore.swagger.io/v2/swagger.json  
    -o samples 
    --use-oas2

From Maven plugin:

...
<configOptions>
    <useOas2>true</useOas2>
</configOptions>
...

reta · 2018-06-25T22:37:09Z

@webron @HugoMario Migrated all JAX-RS part, Spring seems to be behind due to Springfox (does not support Swagger 2.0.x yet). Please take a look guys, thanks!

reta · 2018-07-05T22:53:09Z

src/main/java/io/swagger/codegen/languages/java/AbstractJavaCodegen.java

@@ -145,6 +147,7 @@ public AbstractJavaCodegen() {
        cliOptions.add(CliOption.newBoolean(FULL_JAVA_UTIL, "whether to use fully qualified name for classes under java.util. This option only works for Java API client"));
        cliOptions.add(new CliOption(CodegenConstants.HIDE_GENERATION_TIMESTAMP, CodegenConstants.HIDE_GENERATION_TIMESTAMP_DESC));
        cliOptions.add(CliOption.newBoolean(WITH_XML, "whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML)"));
+        cliOptions.add(CliOption.newBoolean(CodegenConstants.USE_OAS2, "whether to use OpenAPI v2.0 (Swagger 1.5.x) or not (by default, OpenAPI v3.0 is used)"));


For use with Maven plugin

@apixxx

…2.x ones (@Api / @apixxx)

reta · 2018-07-15T20:48:01Z

@HugoMario Seems like we all set, if you mind taking a look please. Thanks!

HugoMario · 2018-07-16T15:47:12Z

thanks a lot @reta, going to look right now.

HugoMario · 2018-07-17T06:43:24Z

Hey @reta sorry for delay, i review code and looks pretty fine for me, but before merge i would like to check the generated output on bin/* files. i'll need a bit more time for it. Just letting you know that i'm working on this.

Also i'm not sure how contributor list works, but i saw that there is not email linked to your profile, this could cause that your PR doesn't count as contribution for Github once the PR is merged.

reta · 2018-07-17T10:59:23Z

Thanks a lot @HugoMario , really appreciate that. I have tested all codegens, no doubts, the compilation for server and client stubs was successful for both oas 2.0 / 3.0 but surely the bugs may escape. Regarding the contributor list, not sure how it works either, but not a big deal if I am not there, getting this feature working would be just great. Please let me know if you discover some issues, I will help to fix them. Thanks!

HugoMario · 2018-07-17T14:05:09Z

thanks again @reta , pretty nice stuff !!!

rockxwre · 2020-02-19T13:49:42Z

@reta @HugoMario
Maybe I am misunderstanding how it should work, but I am having difficulties using the useOas2 option. In the following examples I use jaxrs-jersey for the language argument.

First, I used the following command to list all possible options for the language:

java -jar swagger-codegen-cli.jar config-help -l jaxrs-jersey

which results in a list with options, including useOas2. This suggests that this option is supported.

When I use this command:

java -jar swagger-codegen-cli.jar generate -l jaxrs-jersey -i openapi.yaml --additional-properties useOas2=true

it looks like the option useOas2 is ignored. The generated code is provided with Swagger 3 annotations, instead of Swagger 2.

The command:

java -jar swagger-codegen-cli.jar generate --use-oas2 -l jaxrs-jersey -i openapi.yaml

results in the error: swagger-codegen: error: unrecognized arguments: '--use-oas2'

When using the last command with java as the language, it does work as expected: code is generated with Swagger 2 annotations.

Am I doing something wrong?

reta · 2020-02-20T03:56:04Z

Hey @rockxwre!

Your expectations about the feature are absolutely correct. I am curious what version of the Swagger Codegen you are using? Or you are building from source? The OAS2/OAS3 support had been merged into 3.x.x only.

Thank you!

rockxwre · 2020-02-20T08:38:27Z

Hi @reta,

Thank you for your reply! I used version 3.0.11:

java -jar swagger-codegen-cli.jar version
3.0.11

reta · 2020-02-21T00:04:02Z

Sorry @rockxwre , took me awhile to trace the issue, indeed for command-line tooling the option is not accepted by all server generation libraries (but it is for all client libraries). I will try to submit a fix shortly but if you could use Swagger Codegen Maven Plugin (3.x) or Codegen 2.x (only OAS 2) meantime, it should just work fine. Thank you.

SlavchoArsovski · 2020-08-03T13:35:20Z

Any updates on this issue, the latest version 3.0.21 still uses the old annotations instead of io.swagger.v3.oas.annotations

reta · 2020-08-12T01:44:52Z

@SlavchoArsovski haven't had a chance to work on it, will try to wrap it up with next 1-2 weeks, thanks for pinging.

SlavchoArsovski · 2020-11-05T21:34:12Z

@reta by any chance that swagger codegen for Spring Server Stub and as Java Client will use io.swagger.v3.oas.annotation soon?
What you have added in the comment is for other languages:
x ] jaxrs-spec
[ x ] jaxrs-cxf
[ x ] jaxrs-resteasy-eap
[ x ] jaxrs-resteasy
[ x ] jaxrs-jersey
[ x ] jaxrs-cxf-cdi
[ x ] jaxrs-di

But not Spring Server stub and Java Client

reta · 2020-11-05T23:00:43Z

@SlavchoArsovski yes, the Spring Server stubs were merged in #753, please give it a try, thanks! For Java Client, all of them should support io.swagger.v3.oas, which one you have in mind?

SlavchoArsovski · 2020-11-05T23:39:06Z

Hi @reta, i see on online editor when i generate API that indeed now generated code contains io.swagger.v3.oas.annotation, very cool!

However i have the maven plugin version: 3.0.22 and still generates the code with old swagger annotations, am i missing something?

SlavchoArsovski · 2020-11-05T23:48:37Z

@reta Ahh i see i need to use 3.0.23, i will try it 👍

SlavchoArsovski · 2020-11-06T00:36:23Z

@reta found 2 issues so for with migration from 3.0.21 to 3.0.23 ending with compile errors:

generateg SwaggerDocumentationConfig fails to compile becuase in SwaggerDocumentationConfig.mustache there is same class name from two different packages:
import io.swagger.v3.oas.models.info.Contact;
import springfox.documentation.service.Contact;
having default value on query parametar generates following code:
schema:

name: 'offset'
in: "query"
description: 'Position of first item returned'
required: false
schema:
type: integer
format: int32
example: 100
default: 0
@parameter(in = ParameterIn.QUERY, description = "Position of first item returned" ,schema=@Schema(, defaultValue="0")) @Valid @RequestParam(value = "offset", required = false, defaultValue="0") Integer offset

---> schema=@Schema(, defaultValue="0")) has obsolete comma "," which makes the file with compile error

reta · 2020-11-06T00:44:23Z

@SlavchoArsovski could you please submit an issue to https://github.com/swagger-api/swagger-codegen-generators, I will try to pick it up right away, thank you.

SlavchoArsovski · 2020-11-06T00:51:59Z

@reta #795

Do you know how can i exclude generation of SwaggerDocumentationConfig meanwhile, cause i do not really need it :)

reta · 2020-11-06T00:59:36Z

@SlavchoArsovski

Do you know how can i exclude generation of SwaggerDocumentationConfig meanwhile, cause i do not really need it :)

Hm ... I think you could try these three things:

try to override the template
or (could be easier), apply the code formatter to generated classes, the unused imports should be removed
remove the generated class for SwaggerDocumentationConfig altogether (after generation but before compilation)

reta mentioned this pull request Jun 17, 2018

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

Closed

reta force-pushed the oas3 branch 3 times, most recently from 9b2df9b to b7f68c8 Compare June 25, 2018 22:31

reta changed the title ~~[WIP] OAS 3.0 - Use OAS 3.0 annotations instead of old Swagger 1.5.x / OAS 2.x ones (@Api / @ApiXxx)~~ OAS 3.0 - Use OAS 3.0 annotations instead of old Swagger 1.5.x / OAS 2.x ones (@Api / @ApiXxx) Jun 25, 2018

reta mentioned this pull request Jul 5, 2018

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

Merged

2 tasks

reta force-pushed the oas3 branch from b7f68c8 to 18b928d Compare July 5, 2018 22:52

reta commented Jul 5, 2018

View reviewed changes

reta force-pushed the oas3 branch from 18b928d to 72b5b86 Compare July 5, 2018 23:58

reta force-pushed the oas3 branch 3 times, most recently from b155092 to be8488c Compare July 15, 2018 20:27

OAS 3.0 - Use OAS 3.0 annotations instead of old Swagger 1.5.x / OAS …

a62d442

…2.x ones (@Api / @apixxx)

reta force-pushed the oas3 branch from be8488c to a62d442 Compare July 15, 2018 20:45

HugoMario merged commit aea5e07 into swagger-api:master Jul 17, 2018

reta mentioned this pull request Aug 26, 2020

Add --use-oas2 command line argument support for standalone Swagger Codegen CLI #744

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

reta commented Jun 17, 2018 •

edited

Loading

reta commented Jun 25, 2018

reta Jul 5, 2018

reta commented Jul 15, 2018

HugoMario commented Jul 16, 2018

HugoMario commented Jul 17, 2018

reta commented Jul 17, 2018

HugoMario commented Jul 17, 2018

rockxwre commented Feb 19, 2020

reta commented Feb 20, 2020

rockxwre commented Feb 20, 2020

reta commented Feb 21, 2020

SlavchoArsovski commented Aug 3, 2020 •

edited

Loading

reta commented Aug 12, 2020

SlavchoArsovski commented Nov 5, 2020 •

edited

Loading

reta commented Nov 5, 2020

SlavchoArsovski commented Nov 5, 2020 •

edited

Loading

SlavchoArsovski commented Nov 5, 2020 •

edited

Loading

SlavchoArsovski commented Nov 6, 2020 •

edited

Loading

reta commented Nov 6, 2020

SlavchoArsovski commented Nov 6, 2020

reta commented Nov 6, 2020 •

edited

Loading

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

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

Conversation

reta commented Jun 17, 2018 • edited Loading

reta commented Jun 25, 2018

reta Jul 5, 2018

Choose a reason for hiding this comment

reta commented Jul 15, 2018

HugoMario commented Jul 16, 2018

HugoMario commented Jul 17, 2018

reta commented Jul 17, 2018

HugoMario commented Jul 17, 2018

rockxwre commented Feb 19, 2020

reta commented Feb 20, 2020

rockxwre commented Feb 20, 2020

reta commented Feb 21, 2020

SlavchoArsovski commented Aug 3, 2020 • edited Loading

reta commented Aug 12, 2020

SlavchoArsovski commented Nov 5, 2020 • edited Loading

reta commented Nov 5, 2020

SlavchoArsovski commented Nov 5, 2020 • edited Loading

SlavchoArsovski commented Nov 5, 2020 • edited Loading

SlavchoArsovski commented Nov 6, 2020 • edited Loading

reta commented Nov 6, 2020

SlavchoArsovski commented Nov 6, 2020

reta commented Nov 6, 2020 • edited Loading

reta commented Jun 17, 2018 •

edited

Loading

SlavchoArsovski commented Aug 3, 2020 •

edited

Loading

SlavchoArsovski commented Nov 5, 2020 •

edited

Loading

SlavchoArsovski commented Nov 5, 2020 •

edited

Loading

SlavchoArsovski commented Nov 5, 2020 •

edited

Loading

SlavchoArsovski commented Nov 6, 2020 •

edited

Loading

reta commented Nov 6, 2020 •

edited

Loading