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

package org.apache.juneau.rest.server.docs
API-docs mixin pack — composable @Rest(mixins=...) resources that publish Swagger v2 and OpenAPI 3.1 spec endpoints with Swagger-UI and Redoc HTML mounts.

Four sibling mixins compose into the host @Rest-annotated resource. Each mixin owns its own URL prefix (or single endpoint) and is independently mountable; transitive resolution lets a UI mixin pull in its corresponding spec mixin automatically.

  • SwaggerMixin — spec endpoint at /api, Swagger v2 + Swagger-UI swap.
  • SwaggerUiMixin — HTML-first mount at /swagger, transitively pulls in SwaggerMixin.
  • OpenApiMixin — spec endpoints at /openapi, /openapi.json, and /openapi.yaml; OpenAPI 3.1 + Redoc swap on the content-negotiated /openapi mount.
  • RedocMixin — HTML-first mount at /redoc, transitively pulls in OpenApiMixin.
Composition examples:

// OpenAPI 3.1 spec only — /openapi, /openapi.json, /openapi.yaml. @Rest(path="/api", mixins=OpenApiMixin.class) public class ApiResource extends RestServlet { ... } // OpenAPI 3.1 + Redoc — /openapi, /openapi.json, /openapi.yaml, /redoc. // Transitive mixin resolution pulls OpenApiMixin in for free. @Rest(path="/api", mixins=RedocMixin.class) public class ApiResource extends RestServlet { ... } // Everything — /api, /swagger, /openapi, /openapi.json, /openapi.yaml, /redoc. // This is the post-10.0.0 default for BasicRestServlet / BasicRestResource subclasses. @Rest(path="/api", mixins={SwaggerUiMixin.class, RedocMixin.class}) public class ApiResource extends RestServlet { ... }

The two UI mixins (SwaggerUiMixin and RedocMixin) declare @Rest(defaultAccept="text/html") so that bare browser requests (no Accept header, or Accept: */*) render the HTML view rather than the serializer-default media type. The two spec mixins use Juneau's standard content negotiation unchanged.

The OpenAPI .json and .yaml variants are format-pinned — they ignore the request Accept header and always return the file extension's wire format. This is implemented by explicit serializer dispatch inside the mixin, not by content negotiation, so the pin is robust against Accept: text/html or any other request media type.

See Also:
Since:
10.0.0
  • Classes
    Class
    Description
    OpenApiMixin
    Mixin that publishes the OpenAPI 3.1 spec endpoints for a resource.
    RedocMixin
    Mixin that publishes the Redoc HTML view at /redoc for the OpenAPI 3.1 spec.
    SwaggerMixin
    Mixin that publishes the Swagger v2 spec endpoint at /api/*.
    SwaggerUiMixin
    Mixin that publishes the Swagger-UI HTML view at /swagger.