Introduction

With Spring Boot and springdoc-openapi, Swagger UI does not generate your API description on its own. It loads an OpenAPI document from a URL, so the real configuration question is how to control the JSON endpoint and how to tell the UI which endpoint to fetch.

Separate the docs endpoint from the UI path

There are two related but different settings:

• 'springdoc.api-docs.path changes where Spring publishes the OpenAPI JSON'
• 'springdoc.swagger-ui.path changes where the Swagger UI page itself is served'

For example:

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/docs

With that configuration, the JSON document moves to /api-docs, while the browser UI is served at /docs.

Tell Swagger UI which docs URL to load

If you want explicit control over the document URL used by the UI, set springdoc.swagger-ui.url:

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/docs
springdoc.swagger-ui.url=/api-docs

This is useful when:

• the API docs endpoint is non-default
• a reverse proxy changes the path layout
• the OpenAPI document is served from another location

In simple setups, Springdoc can often infer the correct URL, but adding the property removes ambiguity and makes the configuration easier to reason about later.

Example Spring Boot setup

A minimal application might look like this:

1import org.springframework.boot.SpringApplication;
2import org.springframework.boot.autoconfigure.SpringBootApplication;
3import org.springframework.web.bind.annotation.GetMapping;
4import org.springframework.web.bind.annotation.RestController;
5
6@SpringBootApplication
7public class DemoApplication {
8    public static void main(String[] args) {
9        SpringApplication.run(DemoApplication.class, args);
10    }
11}
12
13@RestController
14class HelloController {
15    @GetMapping("/hello")
16    public String hello() {
17        return "hello";
18    }
19}

With the earlier properties, you would open /docs in the browser and Swagger UI would request /api-docs for the OpenAPI description.

Multiple OpenAPI documents

If you need Swagger UI to present more than one spec, use the indexed urls configuration instead of a single url:

1springdoc.swagger-ui.urls[0].name=public
2springdoc.swagger-ui.urls[0].url=/v3/api-docs/public
3springdoc.swagger-ui.urls[1].name=admin
4springdoc.swagger-ui.urls[1].url=/v3/api-docs/admin

This creates a selector inside Swagger UI so the user can switch between documents. It is a common pattern when one application exposes both public and administrative APIs.

configUrl versus url

You may also see springdoc.swagger-ui.configUrl. That property points Swagger UI to a configuration document rather than directly to an OpenAPI JSON file.

For the usual case of "tell Swagger UI which API docs URL to load," springdoc.swagger-ui.url is the simpler and more direct property. Reach for configUrl only when you specifically need that extra indirection.

Watch for security and proxy effects

If the UI loads but shows no operations, the docs endpoint may still be blocked by security rules, a reverse proxy, or a custom context path. When that happens, the UI page is working but the JSON request fails underneath. Checking the browser network tab is often the fastest way to confirm whether the configured docs URL returns 200, 401, or 404. That distinction usually tells you whether the problem is path mapping or access control.

Common Pitfalls

• Changing springdoc.swagger-ui.path and expecting the OpenAPI JSON endpoint to move too.
• Setting a custom docs path but forgetting that reverse proxies, security rules, or context paths may affect the effective URL.
• Using configUrl when url is the simpler setting for a single spec.
• Assuming the UI is broken when the real issue is that the configured docs endpoint returns 404 or 401.

Summary

• 'springdoc.api-docs.path controls where the OpenAPI JSON is served.'
• 'springdoc.swagger-ui.path controls where the UI page is served.'
• 'springdoc.swagger-ui.url tells the UI which API docs URL to load.'
• Use urls instead of url when you need multiple documents in the same UI.