Springdoc-openapi: Using behind SpringBoot Gateway via Kubernetes

[Selikoff]

I'm trying to migrate from Swagger2 (springfox-swagger-ui) to OpenAPI3 (springdoc-openapi-ui), although I'm running into some problems. I believe it is caused by my app being behind a SpringBoot Gateway in a K8s cluster. Not sure if this is an unsupported feature, config problem, or bug; but here's the two issues I'm seeing:

1. In the old version, the /v2/api-docs JSON file would have a path for host that matched the external address of the server. In the new version with OpenAPI3, /v3/api-docs does return a document, but it shows an internal address in the "server"."url" field, such as: "servers":[{"url":"http://myapp-svc:8080","description":"Generated server url"}]. myapp-svc is only reachable inside the cluster.

2. When I navigate to /swagger-ui.html, the page auto-forwards to an (unreachable) internal address like http://myapp-svc:8080/swagger-ui/index.html?url=/v3/api-docs&validatorUrl=

I'm importing swagger annotations/models (from io.swaggercore.v3) and springdoc-openapi-ui. Also, I previously had a @EnableSwagger2, but I don't know if there is an equivalent in openapi. I did see a @OpenAPIDefinition annotation, although I don't want to hardcode any server addresses. Also, when I did add a server field in the annotation, it only change the value in /v3/api-docs, the /swagger-ui.html still forwarded to an internal address.

Any help would be appreciated.

[M0rfic]

I haven't been in the scenario you describe, but if I understand correctly, you can maybe define a server with a placeholder/variable as a work-around, instead of hard-coding addresses. I've done this by creating an OpenAPI bean instead of using annotations, and you can find below the relevant part of such a configuration:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.servers.Server;
import io.swagger.v3.oas.models.servers.ServerVariable;
import io.swagger.v3.oas.models.servers.ServerVariables;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGeneratorConfig {

    @Bean
    public OpenAPI defineOpenApi() {
        return new OpenAPI()
                .info(defineInfo())
                .components(defineComponents())
                .addServersItem(defineServers());
    }

...

    private Server defineServers() {
        return new Server().url("http://{IP_Address}:8080/my-app")
                           .description("My APP REST API Server")
                           .variables(
                                   new ServerVariables().addServerVariable("IP_Address", new ServerVariable()
                                           //._default("www.example.com")
                                           ._default("localhost")
                                           .description("IP address of My APP REST API Server")
                                   )
                           );
    }
}

Afterwards, when accessing the GUI, you should see something similar to:

[springdoc]

Hi @Selikoff,

The proposal of @M0rfic seems to be a good solution.
Does it resolve your issue ?

[Selikoff]

Nope, the gui continues to forward to the internal address. I think the problem is in the HTML/Javascript. It should be reporting the access URL and using that, then replacing it in the /api-docs. As it stands both the /api-docs endpoint and the GUI endpoint contain the internal address. If I hard-code the URL in the annotation, /api-docs is fixed, but the GUI is not. This seems like a problem with the way the HTML/Javascript is loaded. Either way, we never had this problem with the springfox 2.X version.

[springdoc]

Hi,

This seems to be related to spring-cloud-gateway settings than Kubernetes.
From your description, you should add the following property, on your Spring Boot App that uses springdoc-ui. Please add the following line in your application.properties:

• server.use-forward-headers=true

This will make sure that, the redirects of the swagger-ui, will not go to your internal POD address but automatically to the original(external) host url.

Please let us know, if it works for you.

[Selikoff]

Nope. Tried setting the property on both the gateway and service. Didn't work. It still loads the local URL inside the /v3/api-docs JSON. In addition, assuming my service was running on the /widget endpoint then:

• /widget/v3/api-docs - Contains the internal URL
• /widget/swagger-ui.html : Redirects to internal DNS address, like widget-service:8080/...
• /widget/swagger-ui/index.html : Loads UI but shows pet store (default) project
• /widget/swagger-ui/index.html?url=/widget/v3/api-docs : Loads the right URL, but none of the "Try" commands work because the /api-docs is using a local url.

So far, nothing has worked.

[Selikoff]

This issue should not be closed.

[liaow]

I encountered a similar problem when I configured the spring cloud project(only webflux-ui in gateway module, and microservice api providers behind it). Are there any samples we can refer to?

[bnasslahsen]

You have the springdoc documentation and the demos code:

• https://springdoc.org/index.html#how-can-i-deploy-springdoc-openapi-ui-behind-a-reverse-proxy

If you have any issue, you can provide a minimal, complete, and verifiable example

[oursy]

Add the following line to the application.properties file in the Spring Boot application behind the gateway
server.forward-headers-strategy=framework

[angel-94]

Hi @Selikoff I have the same issue and is exactly like you describe in this comment, the difference is I'm using Kong as Api Gateway

[WeiTangLau]

I am facing the same issue here. I am currently using Spring Cloud Gateway as my API Gateway.

The recommendation mentioned by @oursy, should we put these into all other microservices or at the gateway? And what does it do?

[bnasslahsen]

@WeiTangLau,

Yes you put the property server.use-forward-headers=true, in all your microservices behind SPG in kubernetes.
If you are asking for the propery it self, please have a look at the spring-boot documentation.

You should also make sure, that on your proxy(nginx) level, the correct headers are forwarded to your spring-boot microservices:
Please read the documentation:

• https://springdoc.org/index.html#how-can-i-deploy-springdoc-openapi-ui-behind-a-reverse-proxy