Breaking changes in MicroProfile OpenAPI 4.0

[Andrew Rouse]

MP OpenAPI 4.0 will bring support for producing API documentation in the new OpenAPI 3.1 format. However, it should be noted that this is not compatible with the older OpenAPI 3.0 format supported by previous versions of MicroProfile. The changes aren't huge, but would likely require updates to the tools which users use to consume the OpenAPI documentation.

OpenAPI 3.1 was released in February 2021 and many tools have now added support, so in the new version of MP OpenAPI, our current plan is to only require that implementations produce the new OpenAPI 3.1 format, while keeping the programming API flexible enough to allow vendors to also support generating the older OpenAPI 3.0 format if they wish to.

At the moment, there are only three people regularly participating in the spec, so I'm looking to solicit a broader set of opinions as to whether we're taking the right approach here.

Andrew