CODEWITHSUNDEEP
javaspring-bootswaggerspringdoc-openapi-ui
Mac
Mac

Reputation: 95

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:

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?

Upvotes: 0

Views: 3532

Answers (2)

pod67
pod67

Reputation: 11

The solution above does not work for me, running spring boot 3.3.0 and springdoc-openapi-starter-webmvc-ui in a kubernetes environment.

What works both locally and from a kubernetes container for me is:

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

then swagger is accessed at http://localhost:8080/admin/swagger-ui/index.html

Upvotes: 1

Mac
Mac

Reputation: 95

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.

Upvotes: 1

Related Questions