Springdoc-openapi: 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.

[springdoc]

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... ;-)

[springdoc]

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.

[springdoc]

This feature will be available on the next release: v1.2.19 of springdoc-openapi.

You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique groupName.
The OpenAPI description of this group, will be available by default on:

• http://server:port/context-path/v3/api-docs/groupName

To enable this feature, the following springdoc property needs to be added to your application.yml:

springdoc.api-docs.groups.enabled=true

For the support of multiple OpenAPI definitions, a bean of type GroupedOpenApi needs to be defined.

For the following Group definition(based on package path), the OpenAPI description url will be : /v3/api-docs/stores

@Bean
public GroupedOpenApi storeOpenApi() {
    String paths[] = {"/store/**"};
    return GroupedOpenApi.builder().setGroup("stores").pathsToMatch(paths)
            .build();
}

For the following Group definition (based on package name), the OpenAPI description url will be: /v3/api-docs/users

@Bean
public GroupedOpenApi userOpenApi() {
    String packagesToscan[] = {"test.org.springdoc.api.app68.api.user"};
    return GroupedOpenApi.builder().setGroup("users").packagesToScan(packagesToscan)
            .build();
}

For the following Group definition(based on path), the OpenAPI description url will be: /v3/api-docs/pets

@Bean
public GroupedOpenApi petOpenApi() {
    String paths[] = {"/pet/**"};
    return GroupedOpenApi.builder().setGroup("pets").pathsToMatch(paths)
            .build();
}

For the following Group definition (based on package name and path), the OpenAPI description url will be: /v3/api-docs/groups

@Bean
public GroupedOpenApi groupOpenApi() {
    String paths[] = {"/v1/**"};
    String packagesToscan[] = {"test.org.springdoc.api.app68.api.user", "test.org.springdoc.api.app68.api.store"};
    return GroupedOpenApi.builder().setGroup("groups").pathsToMatch(paths).packagesToScan(packagesToscan)
            .build();
}

For more details about the usage, you can have a look at the following sample Test:

• https://github.com/springdoc/springdoc-openapi/tree/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app68

[dpak-github]

Is it possible to redirect to swagger-ui on different port number using GroupedOpenApi? I'm looking for spring fox SwaggerResourcesProvider alternative. I want to choose a spec for each of my microservice and redirect to that URL without using RouteDefinition etc.

[kanai0618]

So, when i do /v3/api-docs/, i can see all the endpoints , and when i do /v3/api-docs/stores , i can see store related. how do i stop /v3/api-docs/, to not to show anything ?

[bnasslahsen]

Is it possible to redirect to swagger-ui on different port number using GroupedOpenApi? I'm looking for spring fox SwaggerResourcesProvider alternative. I want to choose a spec for each of my microservice and redirect to that URL without using RouteDefinition etc.

If you use the actuator management port, it's possible to have access to the swagger-ui using the actuator port instead.

[bnasslahsen]

So, when i do /v3/api-docs/, i can see all the endpoints , and when i do /v3/api-docs/stores , i can see store related. how do i stop /v3/api-docs/, to not to show anything ?

There is no such a setting.
You seem to be the first one to have this requirement.
You can log a new enhancement request or directly propose a PR which adds a property to disable this endpoint for your case.