I'm having a Quarkus (3.1.0) Rest Service with large input objects. To improve the explanation of these objects I would like to deposit some JSON request examples.
At the moment I'm placing them in resources/META-INF/resources/examples/[...]
and reference them via @ExampleObject(name = "Example1", ref = "../examples/[...])
. This works fine for the Swagger/Openapi-ui, the example is directly usable in the Swagger/Openapi-ui.
The problem appears when I use the Quarkus feature to get the Openapi file and want to use it in an other client like Insomnia or Postman. The generated file contains $ref: ../examples/[...]
entries. However, these relative urls are not meaningful for the use in an other client. This leads to import problems for clients (Insomnia, ...) and client-code-generators (openapi to C#/Java/...).
So my question is, what is the way to go?
Is there an option to let Quarkus export not only the openapi file but also the examples (as a zip or instead of referencing by coping into the Openapi-file)?
Or should I host the examples somewhere on the internet and link to the URLs there?
Or ...?