Search code examples
javaspring-bootswaggerspringdoc-openapi-ui

Customizing Springdocs/Swagger UI paths in Spring Boot 3

I have a very basic Spring Boot 3 service with OpenAPI documentation using Spring Initializr.

plugins {
  java
  id("org.springframework.boot") version "3.2.4"
  id("io.spring.dependency-management") version "1.1.4"
}

dependencies {
  implementation("org.springframework.boot:spring-boot-starter-webflux")
  implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.4.0")
  ...
}

java.sourceCompatibility = JavaVersion.VERSION_21

These two URLs work:

  • http://localhost:8080/v3/api-docs (shows JSON)
  • http://localhost:8080/swagger-ui.html (redirects to http://localhost:8080/webjars/swagger-ui/index.html)

However, because my app is behind a reverse proxy, I want to customize these URLs. Setting the following in my application.yaml file does not work:

springdoc:
  api-docs:
    path: '/api/admin/v3/api-docs'
  swagger-ui:
    config-url: '/api/admin/v3/api-docs/swagger-config'
    path: '/api/admin/swagger-ui.html'

These pages load but navigating to the swagger-ui page shows me the Petstore demo app instead of my own app's documentation. Why?

Solution

  • Answering my own question:

    I needed to add these configs instead:

    springdoc:
  api-docs:
    path: '/api/admin/v3/api-docs'
  swagger-ui:
    path: '/api/admin/swagger-ui.html'
    url: '/api/admin/v3/api-docs'

    Importantly, I had to remove springdoc.swagger-ui.config-url and add springdoc.swagger-ui.url. The reason is that there's a check inside org.springdoc.ui.AbstractSwaggerIndexTransformer.defaultTransformations() like this:

    if(StringUtils.isNotEmpty(swaggerUiConfig.getUrl()) && StringUtils.isEmpty(swaggerUiConfig.getConfigUrl())){
  html = setConfiguredApiDocsUrl(html);
}

    Setting a url and not setting a config-url will trigger the logic needed to make this work.