OpenAPI enhancement

[phillip-kruger]

Small PR that adds the following to the OpenAPI Extension:

1. BuildItem in SPI that contain the OpenAPI Schema. Useful to be consumed by other extensions that wants to generate clients from the OpenAPI Schema.
2. Auto server if no server is set. This will use the default (config quarkus.http.host and quarkus.http.port.

I am working on an extension (still early days) that will generate JS from the Schema, and these features originates from there.

[gastaldi]

I think we should explicitly have serverHost and serverPort here defaulting to ${quarkus.http.host} and ${quarkus.http.port}.

The reason is because the host and port are runtime configs (meaning that the built binary will have the host and port set during the build) and also because an application running in OpenShift won't set these parameters, so it will expose localhost and 8080 through a route (eg.https://registry.quarkus.io)

[gastaldi]

Since the config expects an URL maybe have an Optional<URL> would make sense

[phillip-kruger]

I think we should explicitly have serverHost and serverPort here defaulting to ${quarkus.http.host} and ${quarkus.http.port}.

You mean have new configs that does this ?

[gastaldi]

You mean have new configs that does this ?

Yes, sorry for not being clear

[phillip-kruger]

The auto server feature happens at build time, so if the values are changes in runtime, the user will have to set this the non auto way, for now

[gastaldi]

Yeah, that would have to be a build time config.

I personally think that using quarkus.http.host and quarkus.http.port would work for cases where the app is published in a non-cloud environment. In other cases you'll specify the published URL (which does not match these properties)

[phillip-kruger]

I can open another issue that allows config values in the schema, that we replace in runtime, but that is a separate issue. For now then I'll create new configs that default to quarkus.http.host and quarkus.http.port. Right ?

[phillip-kruger]

@gastaldi actually thinking about it some more, it does not make sense to introduce those two new config options. The whole point of auto server is to add the server entry in the schema if the user did not. The user can already add the server in the schema with config or annotations. So if they are going to go through the trouble to add config, the auto filter is not needed anymore. Make sense ?

[gastaldi]

@phillip-kruger right, that makes sense to me.

On a separate topic, can we use interpolated config values in the @Server annotation?

UPDATE: Just saw it does in the Javadoc: Variable substitutions will be made when a variable is named in {brackets}.

[phillip-kruger]

Mmm, let me check that out tomorrow

[phillip-kruger]

/cc @MikeEdgar

[phillip-kruger]

Ok @gastaldi . During runtime servers can be added to the scheme using the spec's defined mp.openapi.servers, example: mp.openapi.servers=https://xyz.com/v1,https://abc.com/v1.

I have changed this feature to not be always enabled, because when using swagger-ui, these can be some CORS issues between 0.0.0.0 and localhost. So this is really in the case where you want to export the openapi schema document to use with code generation etc. So now this will be added in the export case by default, but need to explicitly set to add to runtime. Hope this makes sense.

[gastaldi]

LGTM

[phillip-kruger]

I added the breaking change label due to the fact that if you are using your own filter (for OpenAPI) and that filter can not run during build time, then you app will now break. This is due to the fact that we are now having a BuildItem that contains the generated OpenAPI document. So Filters needs to handle the case of creating the OpenAPI document during build.

[Denistr]

Hi @phillip-kruger ,
When do you expect release these changes?
As far as I see, there are no these changes in 2.9.2.Final

[phillip-kruger]

They will be in 2.10 in a week or so