Add "root-path" to swagger-ui

[alexey-plotnikoff]

If the quarkus application behind proxy with custom location path swagger UI doesn't work correctly. This PR fix it.

[gsmet]

Thanks for the pull request!

I think we need to clarify the semantic here, also because I suppose this part is probably not the only part that would need tweaking.

Question: would it be possible to use relative paths instead and thus avoiding entirely this issue?

[alexey-plotnikoff]

Question: would it be possible to use relative paths instead and thus avoiding entirely this issue?

Good point. I'll check it.

[alexey-plotnikoff]

@gsmet current plugin generates all links with absolute path:

Do you mean I should change all these links to relative paths?

[michalvavrik]

\cc @MikeEdgar

[MikeEdgar]

I agree that this seems like something that would be handled at a high level than just the Swagger UI. For example, the one link being configured is the backHref that resolves to /q/dev. @alexey-plotnikoff have you tried using the quarkus.http.non-application-root-path configuration for this?

[alexey-plotnikoff]

Thank you @MikeEdgar!
Yes, it works! But I should reconfigure nginx from:

server {
    listen  80;
    server_name quarkus.home.arpa;

    location /nginx/path/ {
        proxy_pass http://host.docker.internal:8080/;
    }
}

to:

server {
    listen  80;
    server_name quarkus.home.arpa;

    location /nginx/path/ {
        proxy_pass http://host.docker.internal:8080/nginx/path/;
    }
}

[alexey-plotnikoff]

@MikeEdgar you solution with quarkus.http.non-application-root-path will change liveness and readiness probes in Kubernetes environment.
So all microservices in Kubernetes will have their own probes instead same for all. For me it is not good solution.
I think will be better add a new parameter for swagger UI only as in this PR.
What do you think?

[MikeEdgar]

I'm not sure if there are other components that should participate with a configuration like the one proposed. I'll let the others chime in on that.

[gsmet]

@cescoffier I think this one should be discussed with you. I'm not entirely sure how we can solve this issue globally.

[alexey-plotnikoff]

@cescoffier What do you think about this PR?

[cescoffier]

Is it the root path for openapi?

[alexey-plotnikoff]

[alexey-plotnikoff]

Maybe I should rename locationPath to rootPath?

[cescoffier]

Yes.

[alexey-plotnikoff]

Done

[cescoffier]

We may have to normalized the resulting path, or do we expect it to be consistent?

[alexey-plotnikoff]

Do you mean I should check a forward slash at the start of swaggerUiConfig.locationPath.get() if it doesn't exists?

[cescoffier]

Yes, also that the given URL is normalized: https://en.wikipedia.org/wiki/URI_normalization

[alexey-plotnikoff]

Done

[cescoffier]

I don't believe we can use a global setting here. The global setting will affect the probes, metrics... Now in such kind of setup, the openapi page is considered public, while the probes (and metrics) are considered private.

The easiest is clearly to configure the extension.

We could imagine another option to declare the openapi routes to be part of the public API and mounted differently, but it will complexify the routing code.

[cescoffier]

I made some comments.

[alexey-plotnikoff]

@cescoffier I made some fixes. Take a look pls.

[cescoffier]

@alexey-plotnikoff can you rebase?
@gsmet, can you re-check this PR once you're back? Probably @phillip-kruger too.

[cescoffier]

@alexey-plotnikoff Any chance for you to rebase the PR?

[alexey-plotnikoff]

@alexey-plotnikoff Any chance for you to rebase the PR?

So much changes!
I'll try.

[alexey-plotnikoff]

@alexey-plotnikoff Any chance for you to rebase the PR?

@cescoffier could someone approve my changes to start GitHub Actions?

[alexey-plotnikoff]

@cescoffier Merging is blocked by @gsmet from Mar 11, 2025. Looks like he doesn't like my PR 😢

[cescoffier]

It looks like there are merge commits.

[quarkus-bot]

Status for workflow Quarkus Documentation CI

This is the status report for running Quarkus Documentation CI on commit 5ef855b.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

Warning

There are other workflow runs running, you probably need to wait for their status before merging.

[quarkus-bot]

Status for workflow Quarkus CI

This is the status report for running Quarkus CI on commit 5ef855b.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

You can consult the Develocity build scans.