springswaggercamundaspringdoc

Having external Swagger JSON along with Springdoc-generated Swagger

I'm developing a Spring application that integrates with Camunda. It exposes both Camunda and custom endpoints. I would like to keep both Swaggers inside the application, like so:

Camunda Swagger

Custom Swagger

But as soon as I add this in the application.properties:

springdoc.swagger-ui.urls[0].name=Camunda
springdoc.swagger-ui.urls[0].url=/path/to/camunda-swagger.json

I can't see the custom documentation, as if these properties would override the default configuration.

I already tried setting the properties' index to 1, but it will lead to an error.

Binding to target [Bindable@38d308e7 type = java.util.Set<org.springdoc.core.properties.AbstractSwaggerUiConfigProperties$SwaggerUrl>, value = 'provided', annotations = array<Annotation>[[empty]], bindMethod = [null]] failed:

Because it will look for the properties with index 0.

Solution

  • I figured out that I have to re-add the default endpoint. The main challenge was understanding the path where the .json is stored (in my case, /v3/api-docs).

    Properties will look like this:

    springdoc.swagger-ui.urls[0].name=Camunda
springdoc.swagger-ui.urls[0].url=/path/to/camunda-swagger.json

springdoc.swagger-ui.urls[1].name=Camunda Integration
springdoc.swagger-ui.urls[1].url=/v3/api-docs

    And now I can properly change definitions and interact with a specific Swagger.

    Switch definitions