Swagger-core: Supporting jakarta namespace

[mzhafez]

Are there any plans to support jakarta namespace (jakarta ee 9) in swagger? With each passing day there are more libraries that have migrated to the jakarta namespace which is incompatible with javax namespace.

The namespace incompatibility will slowly lead to developers having to choose between using swagger or remaining on older versions of libraries that are still compatible with jakarta.

For example, the latest version of Jetty supports Jakarta namespace and is now incompatible with the javax namespace which means that one cannot upgrade to the latest version of Jetty and continue using swagger.

[frantuma]

This is a quite delicate issue and has not been decided yet, and any comment or contribution in this area are more than welcome, however IMO the best direction and the current plan (no ETA yet) is aiming for support of both javax and jakarta namespaces at least for the short - medium term (until things stabilize).

The idea is to have parallel releases of original (let's say javax based) and modified (jakarta based) artifacts, using either direct bytecode manipulation and/or existing specific tools (e.g.
https://github.com/eclipse/transformer), with minor refactoring beforehand (e.g. hardcoded javax etc).

A more comprehensive solution - again depending on how things evolve - would include refactoring the next major version to introduce a compatibility layer, this would however need much more effort than artifact transformation at build/deploy time.

I would say that in any case it's not an option to maintain 2 parallel major release lines for javax and jakarta, if not based on artifact transformation.

Again and as always contributions are appreciated.

[frantuma]

see also https://github.com/swagger-api/swagger-core/issues/3849#issue-779412695

[strangelookingnerd]

See my PR #3852

@frantuma I see your reasoning regarding the support of both namespaces and agree that it would be good from a maintainers POV. However I feel that neither transformer nor a compatibility layer are good solutions from a users perspective.
Looking at Swaggers main dependencies and how they solved this:

JAXB: Clear cut with v3.0.0
Jersey: Clear cut with v3.0.0
Jakarta WS: Clear cut with v3.0.0
Jackson: Supporting both namespaces with shaded JARs (ugly in my opinion). They now provide different JARs seperated by classifier. This is a pain to work with.

I personally would prefer to maintain two major releases for the time being and deprecate the javax version as soon as reasonable.
The future will be jakarta if we like it or not ;)

I'm really willing to support you on this, so please let me know if this is a step towards a solution or not.

[frantuma]

@strangelookingnerd thanks a lot for your contribution in this area!

We are still identifying the best achievable solution, considering both user experience and maintenance effort, and while I see your point in having 2 "clean" separate release lines until javax fades away, we still think that this would mean considerable maintenance effort and duplication, and we still think that an artifact transformation within the same release lines makes more sense for this project.

I feel we are more in a position like Jackson's, as its maintainer says in a comment for a slightly related ticket, and their solution seems to address similar problems, until next major release.

I can understand that it doesn't look so clean, but I'd say this whole thing has not been really "clean" from the start..

Can you maybe elaborate on This is a pain to work with.? Just to have a broader view on impact.

----

I am adding here as reference a set of links related to Jackson work in this area for 2.12 (shading with package renaming and different classifier), even though probably the eclipse transformer tool gets a bit further (e.g. OSGi related changes, etc)

• https://github.com/FasterXML/jackson/wiki/Jackson-Release-2.12
• https://github.com/FasterXML/jackson-modules-base/pull/116
• (but) https://github.com/FasterXML/jackson-jaxrs-providers/issues/132

and

• https://github.com/FasterXML/jackson-jaxrs-providers/pull/124
• https://github.com/FasterXML/jackson-modules-base/pull/95
• https://github.com/FasterXML/jackson-modules-base/issues/112
• https://github.com/FasterXML/jackson-modules-base/issues/96

and

• https://github.com/FasterXML/jackson-jaxrs-providers/issues/129
• https://github.com/FasterXML/jackson-databind/issues/2910
• https://github.com/FasterXML/jackson-dataformat-xml/issues/408

and

https://github.com/search?q=org%3AFasterXML+jakarta

[strangelookingnerd]

I feel it's hard to work with the BOMs and transitive dependencies. For example:

https://github.com/strangelookingnerd/swagger-core/commit/364d5cb6b0c026a33f391479c18011e8e1b57b16?branch=364d5cb6b0c026a33f391479c18011e8e1b57b16&diff=split#diff-efd347097616fc97c8d51278e2eaa1c78fb3effd19ff3c167e907572b4db58d3R203-R229

Maybe I did it all wrong but to my understanding:

<dependency>
            <groupId>com.fasterxml.jackson.jaxrs</groupId>
            <artifactId>jackson-jaxrs-json-provider</artifactId>
            <version>${jackson-version}</version>
            <classifier>jakarta</classifier>
</dependency>

still has transitive dependencies to the "non-jakarta" modules and I would not know how they could change that to be fair.
Shaded JARs are shady...(yes I went there, sorry)...and always come at a cost. Identifying and fixing problems in the transitive dependencies is never fun.

Thinking of a clean solution for a transformation to achieve what was done in my PR gives me a major headache. But maybe thats just me.

[frantuma]

This is good feedback, thanks. I will analyze this a bit more and share some thoughts probably next week, whatever additional comment/thought in the meantime is welcome, particularly on further drawbacks of the transform solution.

[mzhafez]

Any updates on this?

[frantuma]

Jakarta support is planned for upcoming release, probably within next week; we have also considered @strangelookingnerd input and work on this, and we dropped idea to take Jackson path with classifier.

The planned solution still makes use of transformers, but providing a separate artifactId (with -jakarta suffix, e.g. swagger-core-jakarta) along with its own POM with correct dependency hierarchy.

In the medium term we will probably have the default artifacts supporting jakarta, and maintaining a transformed version for javax.

Will keep updates in this ticket

[strangelookingnerd]

@frantuma This is great news and +1 for the planned solution. Any way I could contribute?

[frantuma]

@strangelookingnerd thanks! I'll ping when I have the PR ready / merged, what will be missing is possibly some swagger-jakarta-test module providing tests for the jakarta versions and/or one or more samples added to https://github.com/swagger-api/swagger-samples/tree/2.0/java with some jakarta env, e.g. Jersey, Grizzly, etc

(The PR will introduce a new module swagger-project-jakarta holding in turn the set of jakarta modules swagger-annotations-jakarta, swagger-models-jakarta, etc..)

[frantuma]

please see #3881 implementing what mentioned above.

[frantuma]

Closing as Jakarta artifacts are available since version 2.1.7, see wiki, maven readme and gradle readme.