Design discussion: how to guide Java developers

I understand that OAS is language-agnostic, but wanted to see what others thought about having an official set of Java annotations, which in Java always belong at the spec level.

For illustrative purposes, a Java spec such as JAX-RS defines the specification, the annotations and corresponding programming models. It often has a reference implementation, and several other implementations, but all of them using the same set of interfaces (making apps portable across vendors / OSS providers).

In the Java world there are many possible frameworks that one could use: JEE, Spring, MicroProfile, Dropwizard, the list goes on. So if a Java developers says: “hey, there’s a new official spec, the OpenAPI Specification, I want to use that! Now, what’s the programming model that I should use?”.

By far the most popular choice is the Swagger repo, but we are seeing other (competing) Java programming models emerging that work with OpenAPI v3.

My proposal is to make the Swagger v3 annotations for OpenAPI the official (or at least recommended) interfaces from OAS. So we could release an official package such as io.oas.annotations, which would indicate a clear choice for Java developers - regardless of the Java framework they are using.

We can chat about other programming models later, I thought it would be easier to keep this focused to the annotations first (golden path for most Java apps).

Thoughts?

[evanjbowling]

OpenAPI developers - is there a preferred approach for opening design discussions here? Right now I don’t see any guidance in the form of a CONTRIBUTIONS.md page in the master branch.

Anyways, I have some links that may be of interest to @arthurdm and the others. Have you seen the swagger-codegen project: https://github.com/swagger-api/swagger-codegen/wiki/API-client-generator-HOWTO ? It allows you to generate client/server-side stubs in many languages including a Java JAX-RS language. See a quick example repo that I made here: https://github.com/evanjbowling/swagger-codegen-java-demo

Now, regarding the Java annotations for OpenAPI. Since OpenAPI focuses on RESTful APIs in a vendor-neutral manner, we can simply reuse the JAX-RS annotations for RESTful services. The way to get more Java-focused support would be to go through the JSR process which created JAX-RS in the first place (JSR 311). See these other links for RESTful focused JSRs: https://jcp.org/en/jsr/summary?id=JAX-RS

[raymondfeng]

I would like to see support for bottom-up approach in addition to API first. Having standardized Java annotations for OpenAPI will help. The framework can infer OpenAPI related metadata from its own annotations such as JAX-RS but the OpenAPI ones can be used to express metadata that is not available otherwise.