Springdoc OpenAPI YAML Path Configuration Issue

by

Summary

When you set springdoc.group-configs[1].paths-to-match to a path that ends with .yaml, Swagger UI still requests /v3/api-docs without the extension because the generated URL template does not append the suffix automatically. The key takeaway is that the UI endpoint does not honor the .yaml suffix for group URLs.

Root Cause

  • The URL template used by springdoc‑openapi is hard‑coded to /v3/api-docs for the default group.
  • Group‑specific paths are only prepended; they do not modify the underlying suffix.
  • The configuration property springdoc.swagger-ui.url only affects the initial discovery document, not the per‑group request.

Why This Happens in Real Systems- Many API gateways and documentation tools expect a static endpoint like /v3/api-docs and rely on the client to request the correct file.

  • Adding a file extension changes the resource location, but the underlying framework does not automatically propagate that change to downstream calls.

Real-World Impact

  • Consumers that parse the UI’s generated group URLs will receive a 404 or “Unable to render this definition” error.

  • This can break downstream mock services that depend on the exact group URL format.

  • It creates confusion when manual access works because the raw file can be fetched directly.

  • Bullet list of impacts:

    • API consumers get errors
    • Documentation generation pipelines fail
    • Increased troubleshooting time

Example or Code (if necessary and relevant)

springdoc.group-configs[1].group=customerspringdoc.group-configs[1].display-name=Customers
springdoc.group-configs[1].paths-to-match=${app.public}
springdoc.swagger-ui.url=classpath:/META-INF/springdoc-swagger-ui.yaml

How Senior Engineers Fix It

  • Override the UI’s url property to point directly to the group‑specific endpoint: – Set springdoc.swagger-ui.url=classpath:/META-INF/springdoc-swagger-ui.yaml and then use a custom SwaggerConfig to rewrite the request to .../customer.
  • Alternatively, register a ResourceHandler that rewrites incoming requests to include the .yaml suffix before forwarding to the group endpoint.
  • Result: The UI now fetches http://localhost:8083/v3/api-docs.yaml/customer and renders correctly.

Why Juniors Miss It

  • Juniors focus on the property name and assume that any suffix added to paths-to-match will be reflected in the generated URL.
  • They often overlook that the UI’s internal request builder constructs the path independently of the configuration.
  • Without seeing the source code of SwaggerUiConfigProperties, the behavior appears as a “bug” rather than a design limitation.

Leave a Comment