Customizing Springdocs/Swagger UI paths in Spring Boot 3

Question

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?

Mac · Accepted Answer · 2024-03-27 13:58:42Z

2

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.

answered Mar 27, 2024 at 13:58

Mac

1151 gold badge2 silver badges8 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

pod67 · Accepted Answer · 2024-06-05 05:19:39Z

1

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

edited Jun 5, 2024 at 5:19

answered Jun 5, 2024 at 5:16

pod67

112 bronze badges

Collectives™ on Stack Overflow

Customizing Springdocs/Swagger UI paths in Spring Boot 3

2 Answers 2

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related