MP OpenAPI initial PR

[Arthur De Magalhaes]

Hey everyone,

Earlier this year we agreed on starting a MicroProfile specification for OpenAPI, using the Swagger libraries as the base for it.  I have an initial PR that adds the annotations: https://github.com/eclipse/microprofile-open-api/pull/2

In the coming weeks we will add programming interfaces for configuring different parts of the OpenAPI processor and corresponding OpenAPI models for tree-based model building.  

If a committer could please review the PR, that would be great.   There are some small gaps in the annotations that we're working on, but those are more advanced edge cases, so that current set is pretty complete for most applications.

Thanks,

Arthur

[John D. Ament]

Hi Arthur,

I added some comments to the PR.  I think the copyright claims need to be adjusted.

John

[Arthur De Magalhaes]

Hey John,

Thanks for the review, I will address them shortly.  For the copyright stuff, just wanted to get some guidance:  should we replace "Copyright 2017 SmartBear Software" with "Copyright (c) 2016-2017 Contributors to the Eclipse Foundation", or just add it above it? 

Thanks,

Arthur

[Eric Wittmann]

Arthur the PR looks pretty good.  Really happy to see that the classes are all in the MP packages and that the term 'swagger' is gone.  Nice!  That should be a help to the OpenAPI spec/community, as there continues to be a struggle migrating mindshare from swagger -> OAI.  :)

One question I had was whether there should be any sense of versioning in the package or class names.  It is clear that the annotations only support OAI 3.0, but as the spec evolves (3.1, 3.2, 4.0) how do you anticipate the MP classes to follow?  Just a thought.

[Eric Wittmann]

+1 on this question.  It looks a little weird (to me) having both copyrights in there.

[Arthur De Magalhaes]

Thanks for the feedback Eric, and good question about versioning.  I believe the direction we're going with is that MP OpenAPI 1.0 will support the OpenAPI 3.0 specification, so if in the future we get an OAS 3.1 spec I would suspect we would do a MP OpenAPI 1.1 version, and likewise a MP OpenAPI 2.0 release if we get a OpenAPI 4.0 version (so essentially I think we can track to a N-2 mapping between OAS and MP).

For the individual packages, (addressing a review comment) I enhanced the PR to add package-info files to each of the packages, starting with a version 1.0.  Those would move up independently of the spec version. 

Does that align with your ideas?

Thx,

Arthur

[Arthur De Magalhaes]

Hey John / Kevin / Emily,

Please let me know if there's anything else I can address in that PR.  All current comments were resolved.  

Thanks,

Arthur

[John D. Ament]

Hi Arthur,

Sorry, missed your changes.

However, I'm still struggling with the PR.  To be honest, when it first came through I thought you were with Smart Bear contributing this to us, now I see you're actually with IBM.  

In general, I'm not a fan of us creating a specification that duplicates a well known published standard.  In this case, OpenAPI is already a widely used specification that is defined and implemented the Swagger annotations.  What benefit do we have from duplicating the Swagger annotations in MicroProfile?  More likely than not we have users who are already using these tools, it would make more sense for us to support the de-facto norm than expect people to switch support for a new namespace.  In fact, we've heard this exact feedback from those at JavaOne who are very comfortable with the javax namespace and hope to continue using it in EE4J.

John

[Arthur De Magalhaes]

Hey John,

Good questions.    Our original proposal (a few months) was to indeed take a snapshot of the early Swagger repository for OpenAPI v3 and claim that as part of a MP release.  However, there are some issues with that approach:

- this snapshot will diverge from its original source really quick (not necessarily major breaking changes, but certainly wouldn't see new additions that often go into the Swagger repo)

- the continued use of the word "swagger" was confusing to users - afterall this is about the OpenAPI v3 spec, not the Swagger v2 spec.

- since OpenAPI v3 is not a specification controlled by SmartBear, we have seen a lot more players surface to implement OAS3: https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md    So being a MP spec provides us the flexibility to collaborate with more companies and improve with feedback from various sources

- we want these Java OpenAPI v3 libraries to become a standard much like Swagger v2 spec graduated to become the OpenAPI v3 spec, so it feels natural that we progress from the Swagger namespace into the MP namespace.  

So I think the important point here is that we're not re-inventing the tools for Swagger v2 - those are pretty much set in stone that if you want to do anything with the Swagger v2 spec you should use the Swagger libraries.   What we're proposing is that, given we're in the very early days of OpenAPI v3, we grow the tools for this new spec in a consortium (MP) of companies, just like its specification is governed by a consortium. 

Summary:

Swagger v2 spec (SmartBear) became OpenAPI v3 spec (SmartBear, Google, Microsoft, IBM, Red Hat, etc)

Early OAS3 Swagger libraries (SmartBear, IBM) becomes MP OpenAPI (SmartBear, IBM, Red Hat, etc)

Thanks,

Arthur

[John D. Ament]

Arthur,

Understood.  I realize that OpenAPI is more of a wire protocol, whereas Swagger's role is more of an API/SDK that can generate the wire protocol for you.  What I'm cautious about (and I had the same concerns with DropWizard Metrics integration) is that we're trying to just duplicate what someone already does pretty well.  My belief is that instead of supporting the community and helping nurture it, doing something like this will instead splinter the community.  

I agree that providing a MP Spec makes sense.  However, that doesn't mean that need to redefine the API.  For instance, we didn't define a new REST API or a JSON API, we built on top of the existing Java EE standards.  This means that users end up using APIs across the javax namespace in addition to the org.eclipse.microprofile namespace.

John

[Arthur De Magalhaes]

Thanks for the feedback John.  I think once we move into the proposal of the models and programming interfaces that augment the OAS3 annotations the reasons for going with the MP namespace will become more clear   For example, there are many aspects of the configuration of these library that can be achieved via MP Config (something not planned for the Swagger libs) - the "servers" URL, the name of the packages to scan, a configured filter that lets you work with the interface models (not classes) during annotation processing, etc.   

So the annotation PR is just the initial rev of the spec, but definitely not the whole thing - or even the final thing (we already see some things in the annotations that need to improve).   At the end of the day, the MP OpenAPI libraries will have a lot of enhancements that did not fit the direction of the OAS3 libs from Swagger, but definitely fit with MP and other official EE specs.  

I believe this scenario is different than MP 1.0 endorsing JSON-P and JAX-RS, due to the nature of OAS3 being a very recent spec so io.swagger is not considered to be the de facto impl for v3 (nevermind a JSR) for it - in fact, these other guys actually implemented OAS3 first (https://github.com/RepreZen) and more players are working on similar libs.  

Thx,

Arthur

[Arthur De Magalhaes]

Hey John,

I would like to propose that we go forward with the PR so that we can have some concrete code in GitHub to look at and discuss.  It's just an initial PR / starting point to get these sort of conversations going and the spec reviewed/updated.   We have another PR lined up for the models that we can also push in soon, which would enable wider spec discussions.

What do you think?

[Kevin Sutter]

Arthur,
I think this initial PR looks good.  I just noticed that I hadn't approved the Review changes, which I just did.  Now we just need John's approval and we can merge in your PR. 

Thanks,
Kevin

[John D. Ament]

All,

I think I've made my concerns with this spec clear in this thread.  I believe we are setting a bad path forward by duplicating the existing Open API annotations provided by Swagger.  

When do we expect to see a reoccurring call around OpenAPI to be scheduled?  I think that would better facilitate the discussions to make sure there's a clear path forward.  I won't block anyone from merging this PR though.

John