BasicRestServlet/BasicRestResource Swagger and OpenAPI 3.1

Migrating from 9.4.x? The @Rest(apiFormat=…) annotation member, the juneau.rest.apiFormat system property, the RestContext.getApiFormat() accessor, and the ?Swagger / ?OpenApi query mirrors on group resources are all removed in 10.0.0. Both Swagger v2 and OpenAPI 3.1 are now always mounted via the four-class api-docs mixin pack on BasicRestServlet / BasicRestResource. See the V10 Migration Guide for the full removal table, and API-Docs Mixin Pack for the new composition story.

Any subclass of BasicRestServlet or BasicRestResource gets six auto-generated API-documentation endpoints by default:

URL	Format	UI swap
`GET /api`	Swagger v2 spec	`SwaggerUI` swap for `Accept: text/html`
`GET /swagger`	Same Swagger v2 spec at an HTML-first URL	`SwaggerUI` swap for bare browser GET
`GET /openapi`	OpenAPI 3.1 spec	`RedocUI` swap for `Accept: text/html`
`GET /openapi.json`	OpenAPI 3.1 spec	Format-pinned JSON (ignores `Accept`)
`GET /openapi.yaml`	OpenAPI 3.1 spec	Format-pinned YAML (ignores `Accept`)
`GET /redoc`	Same OpenAPI 3.1 spec at an HTML-first URL	`RedocUI` swap for bare browser GET

See the guide: Generate OpenAPI docs for your API

The six endpoints come from a four-class mixin pack: SwaggerMixin, SwaggerUiMixin, OpenApiMixin, and RedocMixin. BasicRestServlet declares:

@Rest(mixins = {SwaggerUiMixin.class, RedocMixin.class})
public abstract class BasicRestServlet extends RestServlet implements ... { ... }

SwaggerUiMixin transitively pulls in SwaggerMixin, and RedocMixin transitively pulls in OpenApiMixin, so listing the two UI halves is enough to mount all six URLs. See API-Docs Mixin Pack for the full composition reference (custom compositions, transitive resolution, parent-chain aggregation, defaultAccept content-negotiation behavior, format-pinned /openapi.json / /openapi.yaml).

Spec emission

Both spec endpoints lean on the existing SwaggerProvider and OpenApiProvider infrastructure. The mixins do not implement their own emission paths; they expose what those providers already produce at the canonical URLs:

SwaggerMixin returns the Swagger bean produced by the resource's SwaggerProvider. The class-level @MarshalledConfig applies the SwaggerUI swap when an HTML response is being produced.
OpenApiMixin returns the OpenApi bean produced by the resource's OpenApiProvider. The class-level @MarshalledConfig applies the RedocUI swap when an HTML response is being produced.

Custom emission is supported by registering a custom SwaggerProvider / OpenApiProvider @Bean (Spring Boot) or via the bean-store registration path (microservice). See API-Docs Mixin Pack § Spring Boot vs. microservice for the resolution rules, including the @Primary precedence for multi-provider Spring Boot applications.

Mounting on a non-`BasicRestServlet` resource

To get the same six-URL surface on a resource that does not extend BasicRestServlet, declare the mixin pack directly:

@Rest(path = "/api", mixins = {SwaggerUiMixin.class, RedocMixin.class})
public class CustomApi extends RestServlet {
    @RestGet("/items") public List<Item> items() { ... }
}
// Serves /api/items, /api/api, /api/swagger, /api/openapi, /api/openapi.json,
//        /api/openapi.yaml, /api/redoc.

To get only the OpenAPI 3.1 half (no Swagger v2, no /api, no /swagger):

@Rest(path = "/api", mixins = RedocMixin.class)
public class CustomApi extends RestServlet {
    @RestGet("/items") public List<Item> items() { ... }
}
// Serves /api/items, /api/openapi, /api/openapi.json, /api/openapi.yaml, /api/redoc.

To get the OpenAPI half on a BasicRestServlet subclass while dropping the inherited Swagger half, opt out of inheritance for the mixins property:

@Rest(noInherit = {"mixins"}, mixins = RedocMixin.class)
public class OpenApiOnly extends BasicRestServlet {
    @RestGet("/items") public List<Item> items() { ... }
}
// Serves /items, /openapi, /openapi.json, /openapi.yaml, /redoc.

See REST Server — Mixins and Multi-Mount Paths § Parent-chain mixin aggregation for the aggregation rules that govern how noInherit and per-mixin declarations compose across an inheritance hierarchy.

`components.schemas` reuse

The OpenAPI 3.1 emission path collapses duplicated inline schemas into reusable components.schemas entries. Two layers contribute:

Bean-class lift via Swagger v2 definitions. BasicRestServlet carries @JsonSchemaConfig(useBeanDefs="true"), so when the underlying Swagger generator encounters a bean class it lifts the schema into definitions[<beanClassName>] and emits {"$ref":"#/definitions/<beanClassName>"} from each operation slot. The OpenAPI transform rewrites definitions to components.schemas and #/definitions/<name> refs to #/components/schemas/<name> refs.
Inline dedup pass. After the JSON-level Swagger-2.0 → OpenAPI-3.1 transform, BasicOpenApiProviderSession walks every operation parameter, request-body, and response-content schema slot. Inline schemas (those without $ref) that appear two or more times are hoisted into components.schemas and each occurrence is rewritten to a {"$ref":"#/components/schemas/<name>"} pointer. The lifted entry is keyed by the schema's title when present and unique; otherwise a synthesized Schema<N> name is assigned with collision avoidance against existing entries.

The dedup pass runs equally on the spec served by /openapi, /openapi.json, and /openapi.yaml, so all three deliver the same components.schemas shape.

Spec emission​

Mounting on a non-BasicRestServlet resource​

components.schemas reuse​

See also​

Spec emission

Mounting on a non-`BasicRestServlet` resource

`components.schemas` reuse

See also