Request: option to set the OpenAPI version

[EricWittmann]

This comes from someone on the Microprofile OpenAPI gitter chat room:

Franck Arnulfo
@farnulfo_twitter
Hi, is there anyway to have a "dynamic backport of OpenApi version" ?
Context: we use Thorntail v2.6.0 which implement OpenAPI 3.0.1 so /openapi return a 3.0.1 document but our API Gateway (WSO2) only support 3.0.0 so we can't use the /openapi endpoint to configure the API. We can manually import an OpenApi 3.0.0 by editing and modifying the dynamic 3.0.1 but I would like to avoid it. So I was thinking about a way to have the /openapi endpoint to output a back version of the current one. Something like /openapi?version=3.0.0.

[phillip-kruger]

Maybe we allow more that just the version to be overridden in MP Config. Eg. Contact and maybe other field ?

Possible using enums (3.0.0,3.0.1,3.0.2)

[phillip-kruger]

Also maybe change the default to 3.0.2

[famod]

Also maybe change the default to 3.0.2

...or 3.0.3? https://github.com/OAI/OpenAPI-Specification/releases

Context: We are using 3.0.3 in our OpenAPI-files and we noticed Quarkus is exposing the API with 3.0.1...

cc @kenfinnigan

[MikeEdgar]

I think this line in OpenApiAnnotationScanner is to blame.

openApi.setOpenapi(OpenApiConstants.OPEN_API_VERSION);

Perhaps we remove that line and it would allow whatever is given in the static file or the OASModelReader to be available in the result. My concern with adding properties is that the OASModelReader already allows developers to programmatically set values using any configuration source of their choosing and it would be duplicate functionality to some degree.

[phillip-kruger]

Hi All.
I discussed this with @MikeEdgar.

My plan is do the following:

1. When a model file is provided that contains a valid version number, use that. So we remove the "hardcoded" version and allow one to be set from a provided schema.
2. Allow users to set the version using MP Config. (In case they do not want to supply a schema file)
3. Else, use the hardcoded version (that we maybe up to the 3.0.3 version)

How does that sound ?

[famod]

@phillip-kruger That sounds good to me!
The version of smallrye-open-api will certainly limit the version range to some extend, won't it?

[phillip-kruger]

Yes, we might have to set a max.

[MikeEdgar]

One thing to consider about validating the user's input for the version is that it's something we don't really do anywhere else. I.e. let the user/developer decide if they want to output something that isn't technically valid. We've kind of hinted in the past that there are countless ways someone could do the wrong thing (from an OAS perspective) that it could get complicated quickly to verify all the inputs.

[phillip-kruger]

Good point @MikeEdgar . So should we rather not validate the version ? I don't have a strong opinion either way. Maybe start of without any validation and when people log bugs about them setting the wrong version then we add it ? :)