Add Swagger UI for interactive API documentation

[ajantha-bhat]

Summary

• Add quarkus-smallrye-openapi extension to expose the OpenAPI spec at /q/openapi and Swagger UI at /q/swagger-ui in dev mode
• Polaris already uses Swagger annotations (swagger.jaxrs, swagger.annotations) throughout the codebase but does not serve API docs to developers

Motivation

Polaris currently requires developers to reference external OpenAPI spec files or read source code to understand the REST API surface. This change improves API discoverability for developers evaluating or integrating with Polaris.

Changes

• runtime/service/build.gradle.kts — add quarkus-smallrye-openapi dependency
• runtime/defaults/src/main/resources/application.properties — configure schema output directory
• runtime/server/distribution/LICENSE — add license entries for transitive dependencies

Swagger UI is auto-enabled by Quarkus in dev mode only. With quarkus.management.enabled=true, both endpoints are served on the management port (8182):

• http://localhost:8182/q/swagger-ui/
• http://localhost:8182/q/openapi

Production builds do not include Swagger UI unless users explicitly opt in with quarkus.swagger-ui.always-include=true at build time.

Test plan

• ./gradlew :polaris-runtime-service:compileJava :polaris-server:compileJava — builds successfully
• ./gradlew :polaris-server:generateLicenseReport — license check passes
• ./gradlew :polaris-runtime-service:spotlessCheck — formatting passes
• ./gradlew quarkusDev → verified Swagger UI at http://localhost:8182/q/swagger-ui/
• Verified /q/openapi returns the OpenAPI spec in YAML format on port 8182
• CI passes

[dimas-b]

Hi @ajantha-bhat ! The idea look good to me, however, I wonder whether the Swagger UI should be exposed on the main (8181) port or perhaps on the management port (internal)... WDYT?

[ajantha-bhat]

Thanks for the review!

I checked locally — with quarkus.management.enabled=true, Swagger UI lands on the management port (8182), not 8181. The "Try it out" feature won't work from there since APIs are on 8181 and there's no servers section in the generated spec.

quarkus.swagger-ui.always-include and quarkus.swagger-ui.enabled are both build-time properties — no runtime on/off toggle available in Quarkus.

I've removed always-include=true from the defaults so production builds are unaffected. Quarkus auto-enables Swagger UI in dev mode, so ./gradlew quarkusDev will have it on the main port (8181). Users who want it in production can opt in at build time.

The /q/openapi endpoint is available in all modes for tooling and code generation, which is arguably the more valuable part of this change.

[ajantha-bhat]

Correction to my previous comment — I verified in dev mode (quarkusDev) and Swagger UI is still on the management port (8182), not 8181. With quarkus.management.enabled=true, all /q/* endpoints route to the management port regardless of mode.

So the behavior is:

• Dev mode: Swagger UI at http://localhost:8182/q/swagger-ui/, OpenAPI spec at http://localhost:8182/q/openapi
• Production: Not included unless quarkus.swagger-ui.always-include=true is set at build time

The "Try it out" feature won't work from 8182 since APIs are on 8181, but the spec and documentation are still useful for reference. If we want it fully interactive on the main port, we'd need to set quarkus.smallrye-openapi.management.enabled=false.

[flyrain]

Thanks for adding this @ajantha-bhat .
Non-blocker: Should we add integration tests for the OpenAPI endpoint?

[adutra]

all /q/* endpoints route to the management port regardless of mode.

Yes, I think this needs to be exposed on the management port.

[adutra]

./gradlew quarkusDev → verified Swagger UI at http://localhost:8182/q/swagger-ui/

How did you manage to make this work? Running quarkusDev on all modules usually results in errors. I tried instead: ./gradlew :polaris-server:quarkusDev but I couldn't see the Swagger UI 🤷‍♂️