Package org.apache.juneau.rest.server.docs

Class SwaggerUiMixin

java.lang.Object
org.apache.juneau.rest.server.docs.SwaggerUiMixin
public class SwaggerUiMixin extends Object
Mixin that publishes the Swagger-UI HTML view at /swagger.

Sibling of SwaggerMixin (Swagger v2 spec at /api), OpenApiMixin (OpenAPI 3.1 spec at /openapi*), and RedocMixin (HTML-first mount at /redoc). All four classes live in the org.apache.juneau.rest.server.docs api-docs mixin pack.

Declares @Rest(mixins={SwaggerMixin.class}) so transitive resolution pulls in SwaggerMixin (and its /api mount) automatically when this mixin is composed into a host. The two endpoints share the same Swagger document; they differ only in URL surface and content-negotiation defaults.

Configurable mount path:

The default mount /swagger/* can be overridden via the SVL variable ${juneau.swaggerui.path:swagger} — set via system property (-Djuneau.swaggerui.path=docs), environment variable (JUNEAU_SWAGGERUI_PATH=docs), or Config key (juneau.swaggerui.path = docs) to change the runtime mount without subclassing. Resolution happens once at RestContext construction time (SVL resolution in @RestOp(path)).

Override accepts bare token (swagger), leading slash (/swagger), trailing slash (swagger/), or wildcard suffix (/swagger/*) — all resolve to the same mount.

Mixin-only deployment:

This resource is designed for composition via @Rest(mixins=...). The mount path is pinned at the op level by @RestGet(path="/{juneau.swaggerui.path:swagger}/*") on getSwaggerUi(org.apache.juneau.rest.server.RestRequest); a class-level @Rest(paths=...) declaration would be silently ignored under the mixin pattern (see @Rest(paths) Javadoc).

Composition example:

@Rest(path="/myresource", mixins=SwaggerUiMixin.class) public class MyResource extends RestServlet { // Serves /myresource/api (transitively) and /myresource/swagger (this mixin). }

Content negotiation:

The @Rest(defaultAccept="text/html") declaration causes bare browser requests (no Accept header) to render HTML via the SwaggerUI swap. Explicit accept headers (e.g. Accept: application/json) are honored normally.

Sub-context inheritance confines the defaultAccept contribution to this mixin's endpoints — the host's other endpoints retain their own content-negotiation defaults.

See Also:
Since:
10.0.0

  • Constructor Details

  • Method Details

    • getSwaggerUi

      public Swagger getSwaggerUi(RestRequest req)
      [GET /swagger] — render the Swagger-UI HTML view (or the spec, depending on Accept).
      Parameters:
      req - The current REST request.
      Returns:
      The Swagger document.
      Throws:
      NotFound - If no Swagger document is available for this resource.