Comments (9)
@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.
from microprofile-open-api.
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.
from microprofile-open-api.
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.
from microprofile-open-api.
@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.
from microprofile-open-api.
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.
from microprofile-open-api.
In the end, implementations can support both Swagger and OpenAPI if they want, but portable applications shouldn't rely on Swagger annotations.
from microprofile-open-api.
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?
from microprofile-open-api.
@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.
from microprofile-open-api.
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.
from microprofile-open-api.
Related Issues (20)
- Schema has the example property, but no exampleRef HOT 3
- Bump microprofile-parent version and update GitHub CI to align
- Open API 3.1 Conditional Schemas HOT 3
- A configuration example in microprofile-openapi-spec.asciidoc is missing a comma which causes schema parse error HOT 1
- HeaderParam not generating parameter in spec HOT 2
- MP Parent version deviates from MP Parent TCK BOM version HOT 3
- Update JAX-RS to Jakarta RESTful Web Services
- Consider deprecating/removing the `spi` package in the `api` module HOT 9
- [OAS 3.1.0] New security scheme type: mutualTLS HOT 1
- [OAS 3.1.0] Webhooks field in OpenAPI object
- [OAS 3.1.0] Schema changes HOT 5
- [OAS 3.1.0] Operation no longer requires responses HOT 2
- [OAS 3.1.0] New Parameter style values valid for object type HOT 2
- [OAS 3.1.0] More Encoding options can be set for multipart/form-data HOT 1
- [OAS 3.1.0] Callback.expression can now be a `pathItem` reference as well as an object
- [OAS 3.1.0] Summary and description now valid when $ref is set
- [OAS 3.1.0] All security schemes may now define required roles HOT 1
- [OAS 3.1.0] Operation.requestBody now permitted for HTTP methods which don't allow a request body HOT 2
- [OAS 3.1.0] Only one of Paths, Components, or Webhooks is required HOT 2
- [OAS 3.1.0] New restrictions on ServerVariable.enum HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from microprofile-open-api.