Release 1.11.0: OpenAPI Plugin rework: a richer spec, honest schemas and fail-fast diagnostics

[MoonWorm]

Overview

1.11.0 is a rework of the OpenAPI plugin, plus the configuration and bootstrap that feed it. Four headline changes:

• A spec that covers more of your API. filter[…] parameters, sortable fields, limit-offset pagination, deprecation, and a resource identifier described once and reaching every operation that takes one. Resource type is now an enum, which makes included resolvable: a generated client deserializes each member into its concrete class instead of handing you a union to switch on.
• Schemas that tell the truth about responses. required is a create-only promise. A response may legitimately omit any attribute — an unset value is never serialized, sparse fieldsets select a subset, access control withholds what the caller may not see — so attributes are published in three forms: <Type>CreateAttributes keeps required, <Type>UpdateAttributes drops it (PATCH is partial), and <Type>Attributes requires nothing.
• Security the document can back up. @AccessControl requirements become OpenAPI security requirements, with each scope published only on the grant flow that declares it — a scope your client-credentials flow never declares is a reference to nothing. 403 appears on writes a requirement actually guards, and an Authenticated.ANONYMOUS operation is published as public.
• A document the plugin refuses to publish if it cannot vouch for it. Every generated document is walked against itself — a $ref resolving to nothing breaks client generation and response validation — and jsonapi4j.oas.diagnostics decides what that costs you, up to refusing to start.

Beyond the plugin: Spring Boot 3 and 4 from one artifact, a Quarkus compatibility matrix, supported version floors, and configuration validated at startup rather than on first use.

This release contains breaking changes. They are listed first.

Breaking Changes

jsonapi4j.oas.customResponseHeaders is gone

The property and its ResponseHeader / CustomResponseHeaderGroup types are removed. Response headers — and anything else the framework cannot derive — are now expressed as an OasCustomizer:

public class RateLimitHeadersCustomizer implements OasCustomizer {

    @Override
    public void customise(OpenAPI openApi) {
        openApi.getPaths().values().stream()
                .flatMap(pathItem -> pathItem.readOperations().stream())
                .map(operation -> operation.getResponses().get("429"))
                .filter(Objects::nonNull)
                .forEach(response -> response.addHeaderObject("X-RateLimit-Remaining", new Header()
                        .required(true)
                        .description("Number of tokens currently remaining.")
                        .schema(new IntegerSchema())
                        .example(5)));
    }

}

Register it as a @Bean (Spring Boot) or @Produces (Quarkus); with the plain Servlet API pass it to new JsonApiOasPlugin(oasProperties, List.of(new RateLimitHeadersCustomizer())). Customizers run after the built-in ones, so each sees the finished document.

required no longer appears on response attribute schemas

If you generate clients from the document, regenerate them: attributes previously modelled as non-nullable are now nullable, and the write bodies reference <Type>CreateAttributes / <Type>UpdateAttributes rather than <Type>Attributes.

This is a correction, not a relaxation. A required list copied onto responses rejects three things the server is entitled to send: an attribute with no value (never serialized), a sparse-fieldset selection, and an attribute access control withheld. A generated client modelled the field as non-nullable and then failed to read a valid reply.

@Schema(requiredMode = REQUIRED) still means what it says — it is published on <Type>CreateAttributes, and only for resources that have a create.

NONE_OF is gone from scope requirements

AccessControlScopes.Mode and ScopesGroup.Mode keep ANY_OF and ALL_OF. "Deny if the caller holds this scope" cannot be stated soundly in OpenAPI and did not survive being published. Entitlements are unaffected and keep NONE_OF.

Plugins are registered through PluginRegistry

List<JsonApi4jPlugin> is replaced by PluginRegistry, built with PluginRegistry.builder().register(…).build() and passed to the registries and to JsonApi4j.builder(). Spring Boot and Quarkus assemble it for you; plain Servlet bootstraps pass it explicitly.

Configuration is validated at startup

Every enabled plugin's configuration is checked when JsonApi4j is built, and a misconfigured one throws PluginMisconfigurationException with every error at once rather than failing on the first bad key at first use. Serving the OpenAPI document from the same path as jsonapi4j.rootPath, an info.title that is blank, a non-x- extension key, a malformed URL — all now stop the boot.

Supported version floors

Java 17, Spring Boot 3.0.0, Quarkus 3.20, Jakarta Servlet 6.0.0 — each the oldest version still supported. The framework compiles against the floor so that using anything newer is a compile error here rather than a runtime failure in your application. Quarkus 3.15 no longer augments.

The OpenAPI Document

Query parameters are published when you declare them

The framework parses sort, filter[…] and page[…] on every request, but only your operation can act on one — so the document advertises what you declare, not what the request layer tolerates. This is the most common surprise: a working sort that no client can discover.

@OasOperationInfo(
        sortableFields = {"fullName", "email"},
        pagination = {PaginationStyle.CURSOR, PaginationStyle.LIMIT_OFFSET},
        filters = {
                @Filter(name = "region", description = "Filter by region", example = "Asia")
        })
public PaginationAwareResponse<UserDbEntity> readPage(JsonApiRequest request) { … }

sortableFields becomes the parameter's allowed values in both directions. A filter is declared by its dimension, not its parameter name: the framework spells it filter[region], makes it optional and multi-valued as JSON:API defines filters, and bounds it with validation.maxElementsInFilterParam. Limits configured under jsonapi4j.validation are projected into the schemas throughout, so there is nothing to restate.

The identifier is described once

@OasResourceInfo(resourceIdDescription = …, resourceIdExample = …) reaches the {id} path parameter of every operation acting on one instance and the id member of the resource schema. Declaring it per operation is what let one endpoint carry an example and the next one not.

included is resolvable

Every resource schema pins its type to the single value JSON:API allows for it — UsersResource.type is enum: ["users"], not an open string, which is the same rule the framework enforces at runtime with a 409. The union of resource schemas a document may carry declares a discriminator on type, so a generated client deserializes each member into its concrete class.

Deprecation

@OasOperationInfo(deprecated = true)        // one operation
@OasResourceInfo(deprecated = true)         // every operation on the resource

Deprecation only ever widens: a resource takes its operations with it, an operation may retire on its own, and nothing opts back in. Java's @Deprecated is not read — use the attribute.

Paging is discoverable

Collection and standalone to-many responses name their pagination members instead of leaving links an untyped map and meta an open object: self, first, prev, next, last, and pagination.nextCursor / pagination.totalItems. Following links.next and sending pagination.nextCursor back as page[cursor] are the same request. Every member is optional — a cursor-paged read knows there is a next page, not how many there are.

Repetition folded away

Responses and parameters that every operation repeated verbatim are published once under components and referenced from there. Nothing the document says changes — a $ref and the object it points at are the same thing to a reader — but the difference between two operations stops being buried under hundreds of lines of identical error responses. On the sample app it halves the file.

What Access Control Publishes

With the Access Control plugin on the classpath, the document states what it enforces rather than what was hoped for:

Declared	Published as
@AccessControl(scopes = …)	the operation's security, one entry per alternative — (A or B) and (C or D) becomes four
@AccessControl(authenticated = ANONYMOUS)	security: [], OpenAPI's way of saying an operation needs no authentication
any requirement, on a write	403 — reads never carry one, since a denied read answers with an empty document and 200
a requirement on an attribute	a note on that attribute saying it may be absent, and what would reveal it
a requirement's description	appended to the operation's, including entitlements and policies, which OpenAPI cannot state

Each scope is published only on the grant flows whose own scopes declare it. OpenAPI reads an operation's scopes against the scheme naming them, so a scope your client-credentials flow never declares is a reference to nothing — Swagger UI cannot offer it, linters reject it, and it claims a token that flow can never issue. A scope no flow declares fails generation: that is a typo, not a choice.

Access control also describes what it withholds on the attribute itself, so absence is something a caller can act on rather than a mystery:

"creditCardNumber": {
  "description": "User's credit card number. Absent from the response unless the caller qualifies
                  - requires the scopes users.sensitive.read and ownership of the resource."
}

Each of these appears only when its plugin is registered and enabled — an application running neither access control nor sparse fieldsets is never told about them.

Diagnostics

jsonapi4j.oas.diagnostics decides what a document the plugin cannot vouch for costs you, in increasing order of strictness:

Mode	Document is built	A loose end
DISABLED	on first request	ignored — the checks that exist only to report are skipped, not just silenced
WARN (default)	on first request	logged; the document is published anyway
FAIL_ON_REQUEST	on first request	the endpoint answers 500 with a JSON:API error document
FAIL_ON_STARTUP	during startup	the application does not start

FAIL_ON_STARTUP is the only mode that builds the document eagerly, and that is the point of it: every other mode discovers a broken document on whichever request happens to ask for it first, which in a deployed application means discovering it in production. It costs the generation work at every boot, so an application that cannot afford that but must not publish a document it cannot vouch for wants FAIL_ON_REQUEST.

The setting governs reports only. A document that would say something untrue is refused whatever the mode — two schemas claiming one name would publish one of them under the other's shape, and nothing in the document would say so.

Recommended for CI: jsonapi4j.oas.diagnostics=FAIL_ON_STARTUP. On Quarkus this is build-time fixed, like the rest of jsonapi4j.oas.*.

Spring Boot 4, Quarkus, and Version Floors

jsonapi4j-rest-springboot is one artifact supporting Spring Boot 3 and 4. It is compiled against the 3.0.x floor — so a Boot-4-only API is a compile error here rather than a runtime failure in a Boot 3 application — and the same sources are verified against Boot 4.1 and Spring Security 7 weekly and at release.

Quarkus is covered by a compatibility matrix run weekly across the supported range, with the floor at 3.20. The Quarkus extension registers what a native image needs — the OpenAPI model, your attributes classes, the plugin's canned error examples — and the native build is exercised by an integration test.

jsonapi4j.oas.oasRootPath is now honoured identically by all three integrations; Spring Boot previously ignored it.

Other Changes

• A live OpenAPI example. The document generated for the sample app is published at https://api4.pro/oas-example/ and regenerated on every build, so it is what the plugin emits today rather than a screenshot of what it emitted once.
• A golden-file test for the document. All three sample apps assert their endpoint against one shared document, so any change to paths, schemas, parameters, responses or examples surfaces as a reviewable diff instead of going unnoticed.
• The OpenAPI endpoint answers GET and HEAD only, negotiates YAML through Accept as well as ?format=, and serves an ETag so a caller that already has the document gets a 304.
• The compound-docs cache defaults live in one place.
• Dependabot is enabled, configured to leave the floor coordinates alone — a bump there would raise the floor silently, since compiling against a newer version never fails.

Migration Checklist

1. Replace jsonapi4j.oas.customResponseHeaders with an OasCustomizer bean.
2. Regenerate any client built from the document — response attributes are nullable now, and write bodies reference <Type>CreateAttributes / <Type>UpdateAttributes.
3. Replace NONE_OF scope requirements; entitlements keep the mode.
4. Bootstrapping by hand? Build a PluginRegistry instead of passing List<JsonApi4jPlugin>.
5. Check your configuration against the sample apps' config files — invalid values now fail the boot rather than the first request.
6. Declare sortableFields and filters on operations that honour them, or they stay undocumented.
7. Make sure every scope @AccessControl requires is declared under the grant flow that grants it.
8. Recommended for CI: jsonapi4j.oas.diagnostics=FAIL_ON_STARTUP.

Resources

• Documentation: https://api4.pro/
• OpenAPI plugin: https://api4.pro/openapi-plugin/
• Live OpenAPI example: https://api4.pro/oas-example/
• Access Control plugin: https://api4.pro/access-control-plugin/
• Pagination: https://api4.pro/pagination/
• Configuration: https://api4.pro/configuration/
• Compatibility: https://api4.pro/compatibility/
• Release notes: https://github.com/MoonWorm/jsonapi4j/releases/tag/v1.11.0