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

Class OpenApiMixin

java.lang.Object
org.apache.juneau.rest.server.docs.OpenApiMixin
public class OpenApiMixin extends Object
Mixin that publishes the OpenAPI 3.1 spec endpoints for a resource.

Three URL paths are mounted:

  • /openapi — content-negotiated (HTML view via RedocUI swap, plus all serializers registered on the host).
  • /openapi.json — format-pinned: always emits JSON regardless of the request Accept header. Implemented via RestResponse.getDirectWriter(String) so the pin is robust against Accept: text/html or any other media type.
  • /openapi.yaml — format-pinned: always emits YAML regardless of the request Accept header.

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

The mixin declares @Rest(serializers={YamlSerializer.class}) so the /openapi content-negotiated endpoint can serve application/yaml when explicitly requested via Accept. Sub-context inheritance (per the mixin sub-context model) confines this contribution to this mixin's endpoints — the host's other endpoints retain their own serializer set.

Configurable mount path:

The default mount prefix /openapi can be overridden via the SVL variable ${juneau.openapi.path:openapi} — the same variable is reused for all three mounts (/openapi/*, /openapi.json, /openapi.yaml) so a single override relocates the whole surface. Set via system property (-Djuneau.openapi.path=v1/openapi), environment variable (JUNEAU_OPENAPI_PATH=v1/openapi), or Config key (juneau.openapi.path = v1/openapi) to change the runtime mount without subclassing. Resolution happens once at RestContext construction time (SVL resolution in @RestOp(path)).

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

Mixin-only deployment:

This resource is designed for composition via @Rest(mixins=...). The three mount paths (/openapi/*, /openapi.json, /openapi.yaml) are pinned at the op level by @RestGet(path=...) on the handler methods; a class-level @Rest(paths=...) declaration would be silently ignored under the mixin pattern (see @Rest(paths) Javadoc).

Composition example:

@Rest(path="/myresource", mixins=OpenApiMixin.class) public class MyResource extends RestServlet { // Now also serves /myresource/openapi, /myresource/openapi.json, /myresource/openapi.yaml. }

See Also:
Since:
10.0.0

  • Constructor Details

  • Method Details

    • getOpenApi

      public OpenApi getOpenApi(RestRequest req)
      [GET /openapi] — emit the OpenAPI 3.1 document for this resource.

      Standard Juneau content negotiation. Accept: text/html renders the Redoc HTML view via the RedocUI per-media-type swap; other accept types serialize the OpenApi bean using the host's serializer set (plus the YamlSerializer contributed by this mixin).

      Parameters:
      req - The current REST request.
      Returns:
      The OpenAPI document.
      Throws:
      NotFound - If no OpenAPI document is available for this resource.

    • getOpenApiJson

      public void getOpenApiJson(RestRequest req, RestResponse res) throws IOException
      [GET /openapi.json] — emit the OpenAPI 3.1 document as JSON, ignoring the Accept header.

      Format-pinned: always returns application/json. Implemented via RestResponse.getDirectWriter(String) so the pin is not subject to content negotiation.

      Parameters:
      req - The current REST request.
      res - The current REST response.
      Throws:
      NotFound - If no OpenAPI document is available for this resource.
      IOException - If an I/O error occurs while writing the response.

    • getOpenApiYaml

      public void getOpenApiYaml(RestRequest req, RestResponse res) throws IOException
      [GET /openapi.yaml] — emit the OpenAPI 3.1 document as YAML, ignoring the Accept header.

      Format-pinned: always returns application/yaml.

      Parameters:
      req - The current REST request.
      res - The current REST response.
      Throws:
      NotFound - If no OpenAPI document is available for this resource.
      IOException - If an I/O error occurs while writing the response.