[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