Multiple OpenAPI definitions in one Spring Boot project

[hemju]

I am trying to describe two different versions (v1 and v2) with Open API. Basically Swagger UI I should display v1 from http://localhost:8080/v3/api-docs and v2 from http://localhost:8080/v3/api-docs/v2.

With the springfox Swagger Config I could do this through Dockets. Then I had the selection where I could switch the different endpoint definitions.

The library generates one OpenAPI definition per spring-boot application.
We do not expose the /v3/api-docs endpoint, many time for the same application.

[hemju]

@springdoc please don't close the issue right away, because even if you don't allow multiple OpenAI definitions, there is still the question on how to document different versions. Like Springfox Swagger Config allowed with Docket. So can you please tell me if that is possible or not. And if it is possible on how to achieve that. Because I went through the documentation and I only found one way to document all different versions (in our case v1, v2 and internal).

[tvahrst]

We have the same requirements. We currently try to find a 'non-invasive' solution on top of springdoc to allow the definition of multiple APIs - possibly by adopting the Docket-concept from Springfox and replacing/deactivating the main Controller (OpenApiResource). Nevertheless, we would be happy if sprindoc allowed native support for multiple API Definitions... ;-)

Hi guys,

You can disable the springdoc endpoints using configuration property.
If you are achieving the Docket concept, you can propose a pull request and it will be added.

[hemju]

We have the same requirements. We currently try to find a 'non-invasive' solution on top of springdoc to allow the definition of multiple APIs - possibly by adopting the Docket-concept from Springfox and replacing/deactivating the main Controller (OpenApiResource). Nevertheless, we would be happy if sprindoc allowed native support for multiple API Definitions... ;-)

Thomas, could you please share you approach on how you do it. Because I think that many people have a similar requirement

[tvahrst]

Sure. This is 'work in progress'. If we find a solution, we will share it.

[dan-whitehouse]

I just wanted to comment and say that I also require this. The only reason I haven't switched over to spring-doc is the lack of support for this feature.

I have 1 application with 2 totally different data models. It makes little sense for both of them to appear in the same Swagger UI . Nor does it make sense for me to have to make a totally separate application and maintain the shared components.

[sfauvart]

Hello, I don't know if it can resolve your problem but you can use the springdoc.swagger-ui.config-url and make a restcontroller endpoint to generate a json with your multiple api-docs urls as is it described in swagger documentation.
I used them for a microservice gateway.

[tvahrst]

Hi, here a short summary of our attempt do build multi-api support on top of springdoc:

We have a good idea how to map operations (i.e. RestController methods ) to specific OpenAPIs. We build a kind of filter class to define URL and package patterns for every specific OpenAPI (similar to springfox 'Dockets').

But we do have problems with all the possible options to define OpenAPI main attributes, like info, security... For example, it's currently possible to provide a OpenAPI bean as Spring bean, which acts as 'template' for the finally generated OpenAPI. Additionally, it's possible to annotate an arbitrary bean with @OpenApiDefinition (from Swagger) and define for example info attributes. These are global definitions which would apply to all specific OpenAPI Definitions. Finally, springdoc's OpenAPICustomizer is a global customizer and has currently no support for multiple different OpenAPIs

Our idea is to provide additional possibilities to declare OpenAPI properties for specific OpenAPI definitions, which then will override the aforementioned global definitions.

A second challenge is the implementation of OpenAPIBuilder. This is a spring bean (singleton) and references the resulting OpenAPI object during the build-phase and afterwards as 'holder' of the OpenAPI object. As we need multiple OpenAPI objects, we cannot use this singleton bean, but have to create mulitple OpenAPIBuilder instances (for every specific OpenAPI). But there are other spring-beans referencing OpenAPIBuilder, like OperationBuilder which in turn is referenced by RequestBuilder and ResponseBuilder. For all these classes we need multiple instances because they (in-)directly reference OpenAPIBuilder (which holds the OpenAPI object).

(BTW: It would be nice if the class SecurityParser was public. Currently we need ugly reflection tricks to instantiate OperationBuilder, which needs the SecurityParser instance).

This is our 'current score'. Our solution so far is far away from being ready and does not seem to become a good 'open-source candidate' for a pull request ;-) For example, we did not focus on WebFlux support or support for Kotlin Coroutines, as we do not need these features.