De-dupe annotations with available API from Swagger

[johnament]

Most users of OpenAPI are familiar with the Swagger annotations. By duplicating these annotations, which are just representations of the spec, we're creating portability problems for users who may already be using the annotations, as well as introducing extra complexity by needing to switch between the two.

[arthurdm]

@johnament I think there are 3 counter arguments to this:

(1) OpenAPI is a new spec, with most users not using it yet. This proves to be the right time to create an official specification, rather than waiting 2 years when everyone is indeed using either Swagger or RepreZen (or another vendor).

(2) Many people (including IBM, Red Hat and other OAI members) have expressed the need to move away from the Swagger namespace as it confuses users. Swagger v2 and OpenAPI v3 are different specifications, controlled by different entities, with different roadmaps.

(3) I am a committer in swagger-core so I am a fan of the swagger libs, however, it is not suitable as an official library specification. Just look at how the Swagger v2 libraries changed over the last 2 years (when it was supposed to be in a very stable shape). Every month there were changes to it. Look at how the models are regular classes (with equals and hashCode methods) instead of interfaces, and the many different & confusing ways to configure the annotation processing. This can and should be simplified and unified in MP.

[EricWittmann]

I definitely think that having the OpenAPI annotations live within a non-swagger package is important to the continued growth and success of the OAI specification going forward. Red Hat is definitely invested in making sure that our communities move to OpenAPI for API design/documentation and in the Java world that means keeping the term "swagger" out of the package names.

[arthurdm]

@johnament - another comment, as it relates to both annotations and models that you are opposing.

How can the OpenAPI Java specification grow into an official MicroProfile spec and then eventually into a JSR spec without changing the package namespace?

We chose the Swagger library as the core base of this new MP OpenAPI spec for the purposes that it's mostly a mechanical change to get from one into the other - then if you want the added value-adds such as injected MP Config, you can add those on top.

It's the same as when Swagger v2 spec was changed to become OpenAPI v3 - same core library so that it's familiar to users, but with a new namespace and extra value-adds.

[Emily-Jiang]

I am with @arthurdm amd @EricWittmann ! I think it is great to bring swagger api to MP community and drive to get the APIs adopted among MP members. Since swagger library is not a standard, if anyone wants to include this library in their apps, it is fine. The most important thing here is to maintain the APIs and get the APIs implemented by the application servers, e.g. Liberty, Wildfly swarm, payara etc, so that the apps don't need to include the libs and still be portable. Bringing these APIs to MP enables us to release it more frequently and adapt it and evolve to a better usage.

[arthurdm]

Closing this issue as there has been a majority decision (via this issue and via our last hangout) on the current direction of the annotations and models.

[OndroMih]

Looking at Swagger and OpenAPI, OpenAPI v2 is the same as Swagger v2, but OpenAPI v3 is different. It makes sense to me to support OpenAPI v3 annotations and not Swagger v2, because OpenAPI is a more open and standard initiative under Linux Foundation. @johnament what's wrong with that?

[OndroMih]

In the end, implementations can support both Swagger and OpenAPI if they want, but portable applications shouldn't rely on Swagger annotations.

[johnament]

@OndrejM The question is in reference to what Arthur first brought up on the google group, around adding support for OpenAPI v3 into Swagger core

At this point, it's not clear what the plan is for support OpenAPI v3 in Swagger. It seems that this has been decided elsewhere, per #4 (comment) .

I'll note that my ask in this ticket is to avoid annotation duplication, not models. Somehow that got conflated by others in this thread (since the calls were scheduled on top of the Rest Client one, I was never able to join to better explain). Considering that the annotations can be used completely independently, I fail to see the issue with keeping the annotations in tact.

If the goal however from the Open API group is to move away from the Swagger namespace (it wasn't clear when I asked this on the google group), then I think what we're doing is OK. I'm not sure anyone on MicroProfile can answer that, so I wonder where we might be able to get clarity on that.

[EricWittmann]

Thanks for the clarification, @johnament . My take on this is still that it will be beneficial in the long run to move everything away from the swagger namespace to avoid confusion between Swagger and OpenAPI. And I think that includes the annotations.

Hopefully this will avoid developers wondering why they are using Swagger annotations in order to document their OpenAPI v3 APIs.

I would argue that as a result, the correct thing for the swagger community to do (to avoid annotation duplication) is continue to use the Swagger annotations for v2 but use the MP+OAI annotations for OpenAPI v3.