SwaggerUI View Gives Blank Page When Custom View/Spec/Resources Config is Behind Reverse-Proxy

[stevenlmcgraw]

Expected Behavior

The expectation from following the steps to add a contextPath cookie via https://micronaut-projects.github.io/micronaut-openapi/latest/guide/#serverFilter is that SwaggerUI view rendering uses the contextPath cookie value to prepend the path to the static resources configured with micronaut.router.static-resources.* such as follows:

# application.yml

app:
  swagger-context-path: /dev/example # this is an envar reflecting reverse-proxy path for us and different for each namespace

micronaut:
  application:
    name: micronaut-openapi-context-path-issue
  router:
    static-resources:
      swagger:
        paths: classpath:META-INF/swagger
        mapping: /docs/swagger/**
      swagger-ui:
        paths: classpath:META-INF/swagger/views/swagger-ui
        mapping: /docs/swagger-ui/**
      swagger-ui-res:
        paths: classpath:META-INF/swagger/views/swagger-ui/res
        mapping: /docs/swagger-ui-res/**
  server:
    port: 8080

The openapi.properties file is set as follows:

swagger-ui.enabled=true
mapping.path=/docs/swagger
swagger-ui.js.url=/docs/swagger-ui-res/
swagger-ui.theme=muted
swagger-ui.theme.url=/docs/swagger-ui-res/muted.css

Here is the filter for adding the cookie:

package com.example

import io.micronaut.context.annotation.Requires
import io.micronaut.context.annotation.Value
import io.micronaut.http.HttpMethod
import io.micronaut.http.MutableHttpResponse
import io.micronaut.http.annotation.ResponseFilter
import io.micronaut.http.annotation.ServerFilter
import io.micronaut.http.cookie.Cookie
import java.time.Duration

@ServerFilter(methods = [HttpMethod.GET, HttpMethod.HEAD], patterns = ["/docs/swagger-ui*"])
@Requires("\${app.swagger-context-path}")
class SwaggerUiContextPathFilter(
    @Value("\${app.swagger-context-path}") private val contextPath: String
) {

    @ResponseFilter
    fun filterResponse(response: MutableHttpResponse<*>) =
        response.cookie(Cookie.of("contextPath", contextPath).maxAge(Duration.ofMinutes(2)))
}

Note - In our case apps deployed in Kubernetes are behind a reverse-proxy; we know the correct path at runtime from namespace separation of app instances so we do not need to parse headers.

---

Running the app locally and either disabling the contextPath filter or setting the injected @Value to an empty string results in SwaggerUI displaying and functioning as expected.

Actual Behaviour

NOTE - the scenarios in the README.md of the reproducer include details about what is observed in DevTools.

It appears that adding a contextPath cookie via https://micronaut-projects.github.io/micronaut-openapi/latest/guide/#serverFilter or https://micronaut-projects.github.io/micronaut-openapi/latest/guide/#urlParameter is only applying the contextPath to fetching the OpenAPI3 spec YAML file.

Retrieval of the various res/** resources (e.g. res/swagger-ui.css, res/swagger-ui-bundle.js, etcetera) are still being fetched from the root path / plus configured path to resources instead of the contextPath specified plus configured path to resources.

For an app behind a reverse-proxy this causes rendering of SwaggerUI to fail and give a blank page.

I am seeing the contextPath cookie in DevTools, but the URL for fetching any of the res/** resources does not include the value specified.

I do see that the contextPath is being prepended to the URL used to fetch the OpenAPI3 spec itself.

Also, the same behavior is observed when using the URL parameter option suggested by the guide.

---

As far as I can tell this is the correct way to configure things for apps behind a reverse-proxy that also want to change the URL paths involved with OpenAPI3 spec/SwaggerUI - apologies if this is not a bug and I am doing something wrong.

Steps To Reproduce

The README.md of the reproducer has detailed steps for configuring a reverse-proxy and example nginx.conf using nginx on MacOS and running the app for the three scenarios that illustrate things.

Steps for reverse-proxy:

An nginx server configured with a simple reverse-proxy is required to reproduce the issue.

The example-reverse-proxy.conf file in the reproducer repository contains a sample configuration for nginx.

On MacOS the shortest path to running the reverse-proxy is installing nginx via Homebrew:

brew install nginx

Find the nginx.conf file:

nginx -t

Drop the contents of example-reverse-proxy.conf into the nginx.conf file.

brew services start nginx

Here are the steps for the main scenario:

1. Ensure the app.swagger-context-path property in application.yml is set to /dev/example before building.

2. Ensure the reverse-proxy is running.

3. Start the app with ./gradlew run.

4. Go to localhost:8081/dev/example/docs/swagger-ui in a browser; SwaggerUI does not render properly with a blank page displayed; in DevTools we can see the contextPath cookie but the requests go to localhost:8081/docs/swagger-ui-res/** instead of localhost:8081/dev/example/docs/swagger-ui-res/**.

Environment Information

• Operating System: MacOS Sonoma 14.5 (though this issue is not platform-specific)
• Micronaut platform: 4.5.0 (though has been observed in any prior release used with this setup)
• JDK: 17.0.1
• Kotlin: 1.9.23 (though has been observed in any prior release used)

Example Application

https://github.com/stevenlmcgraw/micronaut-openapi-context-path-issue

Version

Experienced this in 3.x as well as 4.x