CODEWITHSUNDEEP
openapiquarkus
JWo
JWo

Reputation: 593

Quarkus: Provide multiple OpenApi/Swagger-UI endpoints

I have an rest api with some endpoints in version 0. I want to replace the current endpoints with a new more generic one (version 1, same path, but different implementation and incompatible params), but need to keep the old ones running for while.

The Question is: Is it possible for Quarkus to provide two OpenApi definitions and two Swagger UI pages?

In my project I included the openapi dependency and let Quarkus generate the OpenApi definition. Is it possible to group the endpoints of version 0 for the one definition and the rest for another one?
I have a setup in mind where one could browse to example.com/v0/docs/ or example.com/v1/docs/. Starting two instances of the API in different versions would be easy, but I think it's not possible without changing the port. I would prefer to have all endpoints accessible on the same port.
Sadly I couldn't find an example for that scenario with quarkus.

If that won't be possible, would it be good practice to have v0 and v1 endpoints in one definition? It looks weird to me. But maybe that's just me.

Upvotes: 1

Views: 2719

Answers (3)

B.Caribou
B.Caribou

Reputation: 1

Use the setting quarkus.smallrye-openapi.additional-docs-directory=META-INF/ in the application.properties and all the .json files from under that folder will be discovered automatically.

Upvotes: 0

martinw
martinw

Reputation: 364

The answer is no, as far as I can see.

Quarkus reduces complexity of deployment and operation but the price is that you do not have access to all the freedom that a full featured application server gives you (like deploying two versions of the same application under different URLs).

But: Since Quarkus is "containers first", you should be able to deploy v0 and v1 in different containers, listening to different ports but being merged into the same URL structure by an upstream web server like Apache or NGINX.

Having both versions in one Quarkus applications seems to invite lots of trouble, e.g. about versioning your application(s) correctly.

Upvotes: 2

Frank Hopkins
Frank Hopkins

Reputation: 695

I'd find it weird if I needed to look up the new version of the endpoint in a totally different swagger ui / file. It is the same service after all.

Imho the typical approaches are:

  1. either keep the old service as is and run it as the old version, run the new service separately (and at some point switch the old one off)
  2. consider it the same service with some legacy endpoints and put everything in the same spec. If you want to group old endpoints separately you could use swagger tags for that. https://swagger.io/docs/specification/grouping-operations-with-tags/

Upvotes: 0

Related Questions