[REQ] Is it possible to use swagger 3 annotation in place of swagger 2 for java?

[TehBakker]

Is your feature request related to a problem? Please describe.

I've migrated my API from swagger codeGen and swagger2 to openApi codeGen and openApi.
I used to expose my paths and json spec to customer through springfox, and I want to update that as to expose an openApi spec file.
Following the guide for migration found https://springdoc.org/migrating-from-springfox.html I see the annotation used by openApiCode are still the "swagger2" one

Describe the solution you'd like

Is there a way to configure that in my pom.xml as to use the newer annotation ?
Is there anyway to configure that ?

Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.

@ApiParam -> @parameter
@ApiOperation -> @operation
@Api -> @tag
@ApiImplicitParams -> @parameters
@ApiImplicitParam -> @parameter
@ApiIgnore -> @parameter(hidden = true) or @operation(hidden = true) or @hidden
@apimodel -> @Schema
@ApiModelProperty -> @Schema

[InfoSec812]

This is related to the work being done in #5803 and we should probably address this at a higher level than just the Spring generator to make it usable for all Java generators. @videki and others have already started work on the updated templates, but the main bottleneck is that the AbstractJavaCodegen uses the older annotations. I guess that my question becomes "Do we need to maintain support for the older Swagger 2 annotations or should we move completely to Swagger3/OAS?"

[PieterJanMindCapture]

I just tried this, it's available from

                    <groupId>org.openapitools</groupId>
                    <artifactId>openapi-generator-maven-plugin</artifactId>
                    <version>5.3.1</version>

and you must use configOptions:
true
true
false

this will then generate the OAS3 annotations from:

io.swagger.core.v3
swagger-annotations
2.1.x


io.swagger.core.v3
swagger-models
2.1.x

and you can remove the Springfox libraries annotations (OAS3).

    <!--            <groupId>io.springfox</groupId>-->
    <!--            <artifactId>springfox-swagger2</artifactId>-->
    <!--            <version>${springfox.version}</version>-->
    <!--        </dependency>-->

however, there are some issues:
the generated code will still generate the OAS2 import statements, even though they are unused. (auto-import clean from IDE fixes this on the fly)

However, a breaking issue with that the OAS3 annotation: @hidden is generated on the parameters, but this annotation is not applicable to the parameter scope. and so causes a compile issue.

perhaps 5.4.0 fixes this?

[mprachid]

@PieterJanMindCapture what are the configOptions to set please ?

[PieterJanMindCapture]

generator options are here:
https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md

configOptions

in generator options: set: configHelp to true and run maven, it will print out all options for your version of the plugin, instead of generating files.

For "java" generator options are here, and specifically for language/generatorName= "spring" the configOptions are also documented here:
https://openapi-generator.tech/docs/generators/spring/

[eguller]

for springboot is is possible with 5.3.1 version

<configOptions>
<library>spring-boot</library>
    <!-- all other config options -->
    <!-- following is added in v5.3.1 and import oas3 packages instead of swagger2.
    <oas3>true</oas3>
</configOptions>

see related issue
#9775

[tofi86]

@eguller thanks for the pointer!

However, with the settings mentioned in your example and the ones in the MR #9775

                        <configuration>
                            <inputSpec>${project.basedir}/src/main/resources/v1/openapi.yaml</inputSpec>

                            <generatorName>spring</generatorName>

                            <configOptions>
                                <library>spring-boot</library>
                                <oas3>true</oas3>
                                <useSpringController>true</useSpringController>
                                <useSpringfox>false</useSpringfox>
                            </configOptions>
                        </configuration>

Some models are generated with v3 annotations AND v2 annotations, for which the import fails:

...
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
...
import io.swagger.v3.oas.annotations.media.Schema;

Also, these imports are not used anywhere.

Any other configuration ideas to overcome this?

Or is this a bug from the oas3 feature? (cc @welshm)

Thanks!
/Tobias

[welshm]

Hi @tofi86 ! So I did accidentally break some of the annotations for some of the mustaches I missed.

However, I think these have since been fixed by some wonderful work from @cachescrubber in #11181 and two other improvements after that.

Hopefully that will be in a release soon 🤞

[tofi86]

Hi @welshm, well then we‘re looking forward to the next release! 👍

[SamaNaresh]

org.openapitools
openapi-generator-maven-plugin
5.3.1

I don’t see the version '5.3.1' anywhere. Can you please explain how I can get 5.4.0 version. as you mentioned 5.3.1 have some issues

[cachescrubber]

@SamaNaresh 5.4.0 has been officially release and is available from the usual distribution points.

[PieterJanMindCapture]

It works. Thanks

[PieterJanMindCapture]

actually... there's still an issue with the generation of:

@parameter(hidden = true) final ServerWebExchange exchange

and that is that: you can't assume that the project is running in a Reactor web context.

The default in spring is : servlet web context, if both servlet context (eg the so called spring-mvc) and a reactive libraries are found on the classpath it will default to picking Servlet web context.

One can have a project that is mostly rest-endpoints in servlet spring-mvc/boot web context, and have some select controllers return a webflux react Mono/Flux response.

However, in the default web servlet context, the bean ServerWebExchange does not exist.
I've tried mocking it as well as creating a no-op bean, since, in the servlet context, this is completely unused.
The project will not start without attempting to inject this bean, so I'm having to comment this out in the generated code.

Now, I've also noticed that the generated response is:
produces = { "application/json" }
And I think this should be:
produces = { "text/event-stream"}

instead to confirm with the spec.
However, even setting text/event-stream in the yaml/json spec file, the generator will still generate:
produces = { "text/event-stream", "application/json" }

with both present, and that is because in OAS3, it is not possible to override the "default" content-type anymore.

[cachescrubber]

The media-type issue is fixed with #11526

[robinjhector]

Is there any way of making the <generatorName>java</generatorName> with configOptions -> library=resttemplate generate annotations using swagger v3 annotations?

If I use <generatorName>spring</generatorName> and configOptions -> oas3=true it works great, but I cannot get the java generator to do the same. Any idea why?

[welshm]

Is there any way of making the <generatorName>java</generatorName> with configOptions -> library=resttemplate generate annotations using swagger v3 annotations?

If I use <generatorName>spring</generatorName> and configOptions -> oas3=true it works great, but I cannot get the java generator to do the same. Any idea why?

The option is currently only available for the spring generator unfortunately. You can open a feature request or contribute to creating it for the Java client :)

[merrillgh]

Is there any place to support OpenAPI 3+ in CXF?

[aabdelli03]

I have the same issue with swagger codegen 3.0.34 , i did change swagger-annotations to io.swagger.codegen.v3 but still have a probleme with generated Apis.
here is an example
@ApiOperation(value = "Create element t", nickname = "createElementt", notes = "", response = IdDto.class, tags={ "element-controller", })
@ApiResponses(value = {
@ApiResponse(code = 200, message = "the request was processed successfully", response = IdDto.class),
@ApiResponse(code = 400, message = "client side error", response = ErrorDto.class),
@ApiResponse(code = 401, message = "unauthorized call", response = ErrorDto.class),
@ApiResponse(code = 406, message = "not acceptable call", response = ErrorDto.class),
@ApiResponse(code = 500, message = "server side error", response = ErrorDto.class) })
@RequestMapping(value = "/technical-products",
produces = { "application/v1+json; charset=utf-8" },
consumes = { "application/v1+json; charset=utf-8" },
method = RequestMethod.POST)
ResponseEntity createElementt(@parameter(in = ParameterIn.HEADER, description = "" ,required=true,schema=@Schema()) @RequestHeader(value="Authorization", required=true) String authorization, @parameter(in = ParameterIn.DEFAULT, description = "", required=true, schema=@Schema()) @Valid @RequestBody ElementCreatFullDto body, @parameter(in = ParameterIn.HEADER, description = "" ,schema=@Schema())")) throws ApiException;

all the annotations are not found either with imports i don't find them