Evaluate OpenAPI 3.1 for changes (to update this spec)

[EricWittmann]

In a couple of months, the OpenAPI spec should be releasing version 3.1. We should evaluate that release and figure out what changes we might need to make to this spec to support it. Also should we support multiple versions of the OpenAPI spec or only the latest??

[jmini]

Do we know if 3.1 is backward compatible with 3.0?

I would tend to think that we should support only one version of OpenAPI (the latest — once it is released of course), but of course if they bring changes that results in Java-API Breaking changes, then this idea might not work well.

[EricWittmann]

This is still on my to-do list but I haven't had a chance to tackle it yet. I agree with you though that we should try to support only one version of OpenAPI.

[EricWittmann]

So here is a summary of the changes in 3.1 vs. 3.0.2:

• Info has a new property summary - "A short summary of the application".
• Discriminator is now extensible
• Added a Security Scheme type for MTLS: mutualTLS
• The spec now reserves a namespace of extension property names: x-oas-

There are indications in the OpenAPI spec that a version 3.0.3 will be released before 3.1.0 is released. But I'm just guessing based on the text of the specification found on the v3.1.0-dev branch:

https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev/versions

[jmini]

I did not found this issue this morning an created a duplicate: #431 (now closed).

---

The first 3.1.0 version (3.1.0-rc0) has been released:
See: 3.1.0-rc0 release notes

Released (3.1.0-rc0) specification documentation:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md

Changes related to the upcoming 3.1.0 release should be submitted at the development branch.

So the "SNAPSHOT" version of the 3.1.0 specification documentation is on this branch:
https://github.com/OAI/OpenAPI-Specification/blob/v3.1.0-dev/versions/3.1.0.md

---

I have created a new label to mark all the issues required to be compatible with OpenAPI 3.1.0 (See the OAS 3.1.0 label).

---

We need to decide for a strategy regarding the adoption of this spec update for Microprofile-OpenAPI. If I remember well, we decided a long time ago that Microprofile-OpenAPI does not want to support multiple OpenAPI versions.
We could say that our version 2.0 will provide support for OpenAPI 3.1.0 (when it is out).

---

If we decide to use the master branch for OpenAPI version 3.1.0, maybe we can create a released version 2.0-MR2 release prior to the integration of the new OpenAPI features.

---

We can also decide to store all changes required by OpenAPI 3.1.0 on a specific branch.

---

I would like to start working on this, as the release candidate phase of OpenAPI release might be a good timing to provide feedback to the spec team.

[arthurdm]

I think it makes sense for MP Open API 2.0 to support OAS 3.1 @msmiths @EricWittmann @phillip-kruger @MikeEdgar

[MikeEdgar]

@arthurdm - I agree, but is there enough time? Also, given how new 3.1 is, do we need to consider the downstream tooling support for 3.1 and provide configuration to keep 3.0.x output? It may not be necessary, but I want to raise the question.

[msmiths]

@arthurdm I agree with @MikeEdgar that time could an issue. 3.1.0 is only at RC0 at the moment, so it could delay getting MP OpenAPI 2.0 released.

[arthurdm]

good point. I guess MP OpenAPI 2.1 could be an option to support OAS 3.1.0 in the future.

[jmini]

I guess MP OpenAPI 2.1 could be an option to support OAS 3.1.0 in the future.

According to the release notes of OAS 3.1.0-rc0 they are introducing breaking changes. So probably we will have to bump to MP OpenAPI 3.0.

Anyway doing a release of MP OpenAPI soon for OAS 3.0.x and postponing OAS 3.1.0 support to an other release is fine for me as long as we can have a place to start to work on OAS 3.1.0 (I would prefer a branch here, if this is not possible I will do it on my fork).

[rk3rn3r]

+1 Would be great to have patternProperties from that JSON Schema draft 2020-12 extension which is part of OAS3.1.

[Azquelt]

Here are the large changes which I think require a change to the API:

• [OAS 3.1.0] Update the checks for the openapi attribute #434
• [OAS 3.1.0] Add summary to Info #435
• [OAS 3.1.0] Add identifier to License #436
• [OAS 3.1.0] PathItem supports references in the Components object. #437
• [OAS 3.1.0] New security scheme type: mutualTLS #582
• [OAS 3.1.0] Webhooks field in OpenAPI object #583
• [OAS 3.1.0] Schema changes #584

The Schema changes will be the largest and that issue will likely need broken down further.

There are also some smaller changes for which we may want to add extra tests and may need to update API documentation but shouldn't require any changes to method signatures:

• [OAS 3.1.0] Operation no longer requires responses #585
• [OAS 3.1.0] New Parameter style values valid for object type #586
• [OAS 3.1.0] More Encoding options can be set for multipart/form-data #587
• [OAS 3.1.0] Callback.expression can now be a pathItem reference as well as an object #588
• [OAS 3.1.0] Summary and description now valid when $ref is set #589
• [OAS 3.1.0] All security schemes may now define required roles #590
• [OAS 3.1.0] Operation.requestBody now permitted for HTTP methods which don't allow a request body #591
• [OAS 3.1.0] Only one of Paths, Components, or Webhooks is required #592
• [OAS 3.1.0] New restrictions on ServerVariable.enum #593

Most of these are likely to be small and some may not need any action.

My reference for the changes is the OpenAPI spec release notes for 3.1.0 and all of its RCs. The list of changes here is shorter because many of the changes there fall under schema changes

[Azquelt]

@MikeEdgar Having evaluated the changes required, I think we can close this issue?

[MikeEdgar]

@Azquelt, I agree. Closing now.