Package org.apache.juneau.rest.server.ops

Class RouteIndexMixin

java.lang.Object
org.apache.juneau.rest.server.ops.RouteIndexMixin
public class RouteIndexMixin extends Object
Mixin that exposes a content-negotiated index of all @RestOp-annotated methods on the host resource (and any other mixins on it) at /options (configurable).

The op returns a RouteDescriptions POJO rather than writing a fixed format, so Juneau's content negotiation serves a browsable HTML page (with clickable route links), JSON, or XML based on the request Accept header — mirroring the way NavigationMixin.getChildren(...) produces a navigation page while still serving JSON to API clients. The host therefore needs serializers configured (e.g. via BasicUniversalConfig / a Basic* servlet base); a bare @Rest host with no serializers cannot content-negotiate the listing.

Sibling of EchoMixin (/echo/*) and AdminMixin (/admin/*). All three classes live in the org.apache.juneau.rest.server.ops ops/introspection mixin pack.

Configurable mount path:

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

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

Migration note (10.0.0): Earlier development snapshots of this mixin mounted at both /options and /routes as historical aliases on a single op. That dual default has been collapsed to a single SVL-configurable mount as part of the "single path per op" principle. Deployers who relied on the /routes alias must now set -Djuneau.routeindex.path=routes or compose a second instance with the override.

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.routeindex.path:options}") on getRoutes(org.apache.juneau.rest.server.RestRequest); a class-level @Rest(paths=...) declaration would be silently ignored under the mixin pattern (see @Rest(paths) Javadoc). Note also that the route-index walks the host's RestContext via resolveHostContext(org.apache.juneau.rest.server.RestContext) — it only makes sense in a host-attached composition, not standalone.

Composition example:

@Rest(path="/api", mixins=RouteIndexMixin.class) public class ApiResource extends RestServlet { @RestGet(path="/items", summary="List items") public List<Item> items() { ... } }

Output:

Each @RestOp-annotated method on the host (and on any other mixins on the host) is surfaced as a single entry, ordered by path. Rendered as JSON (for an Accept: application/json request) the listing looks like:

[ { "path": "/items", "methods": ["GET"], "summary": "List items", "description": "", "deprecated": false } ]

Excluded entries:

  • The route-index endpoint itself (it shouldn't echo its own listing).
  • Any operation marked @OpSwagger(ignore=true) — consistent with how those operations are excluded from the OpenAPI spec by BasicSwaggerProviderSession. Convention endpoints (favicon, robots, version, etc.), static-files mixin handlers, and the sibling ops-pack endpoints all carry that annotation and are therefore omitted from the index, matching the audience separation: api-docs is for documented public API; route-index is for the same surface but in machine-readable form.
  • Lifecycle / filter beans — only methods with a RestOp-group annotation (GET / POST / PUT / DELETE / PATCH / OPTIONS / RestOp) are listed; RestStartCall / RestEndCall / converters / matchers are not.

The handler itself carries @OpSwagger(ignore=true) so the route-index endpoint is excluded from the OpenAPI spec.

See Also:
Since:
10.0.0

  • Constructor Details

    • RouteIndexMixin

      public RouteIndexMixin()
      No-arg constructor — route-index has no configurable state.

  • Method Details

    • getRoutes

      public RouteDescriptions getRoutes(RestRequest req)
      [GET /options] — return the route index as a content-negotiated POJO.

      Returns a RouteDescriptions list rather than writing a fixed format, so the response is content-negotiated through the host's configured serializers: an Accept: text/html request renders a browsable table (with each path as a clickable link), while application/json / text/xml clients receive the same entries in their requested format — mirroring the way NavigationMixin.getChildren(...) backs the child-resource navigation page.

      Parameters:
      req - The current REST request — supplies the host RestContext.
      Returns:
      The route-index entries, ordered by path.

    • collect

      public RouteDescriptions collect(RestContext hostCtx)
      Collects the route-index entries from the supplied host RestContext and any of its registered mixin sub-contexts (test/inspection helper).
      Parameters:
      hostCtx - The host context. Must not be null.
      Returns:
      A list of route-index entries, ordered by path.