Providing separate OpenApi definitions

Question

We have a service that provides 2 separate Rest API. One is a simple API that our customers use and the other one is an internal API used by a web application.

Our customers are not able to access the web API so I would like to be able to provide 2 separate OpenApi specifications, one for our customers and one for our web developers.

I found a pretty straightforward way to achieve what I want by creating an endpoint, retrieve the OpenApi document and filter out the tags belonging to the customer API.

@Inject
OpenApiDocument document;

@Operation(hidden = true)
@GET
@Produces("application/yaml")
public Response customer() throws IOException {
    OpenAPI model = FilterUtil.applyFilter(new MyTagFilter("mytag"), document.get());

    String result = OpenApiSerializer.serialize(model, Format.YAML);

    return Response.ok(result).build();
}

One problem is that the injected OpenApiDocument instance is null in development mode. The OpenApiDocumentProducer seems to be missing some classloader magic that is present in the OpenApiHandler class. Another minor problem is that the filter “MyTagFilter” also needs to filter out Schemas not used by any tagged PathItems and the code becomes somewhat dodgy.

Is there a better way to solve my problem?
Would it be possible to fix OpenApiDocumentProducer to provide a non null and up to date OpenApiDocument in developer mode?

Similar question: Quarkus: Provide multiple OpenApi/Swagger-UI endpoints

score 0 · Answer 1 · answered May 04 '23 at 15:27

Unfortunately, as far as I know, it is not possible to have two separate OpenAPI specifications. However, there are a couple of workarounds that you can consider:

The first option is to separate the APIs into two separate Quarkus applications. This way, each API will have its own OpenAPI specification.
Another option is to include all of the endpoints in a single OpenAPI specification, even the internal ones that you don't want to expose publicly. Then, after generating the specification, you can post-process the openapi.yaml file using a YAML library and remove the internal endpoints. This will give you a clean specification that you can import into Swagger UI. Keep in mind that you have to protect internal endpoints with authentication.

Providing separate OpenApi definitions

1 Answers1