OpenAPI 3.1 Support and Migration

中文契约 · Download minimal JSON · Download minimal YAML

This page describes the OpenAPI 3.1 contract of Java 5.7.7. See the release notes and version reference for version-specific capabilities. Knife4x Go is versioned independently; see the Go release notes. This document does not change any starter or default setting.

Supported versions

OpenAPI defines its feature set at the major.minor level. 3.1.x therefore shares one OpenAPI 3.1 feature set without patch-specific capability forks, and offline export reuses the shared version predicate instead of a private patch allowlist. Existing OpenAPI 3.0.x behavior remains available. OpenAPI 3.2.x consumption is documented in the OpenAPI 3.2 support matrix; published 5.7.7 / Knife4x v0.8.6 still ship the 3.1 contract on this page and keep 3.2 on a separate path.

Document version	UI	Status	Contract
Swagger / OpenAPI 2.0	Vue 3	Maintenance	Provided by the openapi2 starters; no OAS 3.1 expansion
OpenAPI 3.0.x	React	Supported	Existing parsing, debugging, export, and change-tracking paths remain
OpenAPI 3.1.x	React	Supported	Shares one feature set, subject to the boundaries below
OpenAPI 3.2.x	React	Published	Never guessed or treated as 3.1; see the OpenAPI 3.2 matrix

Unreleased source upgrade

The source branch uses springdoc 2.9.1 with Swagger Jakarta annotations/models/core 2.2.55. Boot3 MVC, WebFlux and standalone aggregation require Boot 3.4.7+ on the 3.4 line or 3.5.1+ on the 3.5 line (Framework 6.2.8). Raw Java Object properties and List<Object> items allow any JSON value in OAS 3.1. The table below records the published 5.7.7 matrix; see the source dependency changes and migration configuration.

springdoc generation matrix

Spring Boot	starter / springdoc	Generated document	Verified path	Evidence
Boot 2.x	non-Jakarta openapi3 / springdoc 1.8.0	OpenAPI 3.0.x	Existing compatibility baseline	#737
Boot 3.x WebMVC	Jakarta openapi3 / springdoc 2.8.9	OpenAPI 3.1 when explicitly enabled	Real /v3/api-docs → Java smoke → React / SchemaEngine	#737
Boot 3.x WebFlux	Jakarta webflux / springdoc 2.8.9	OpenAPI 3.1 when explicitly enabled	Real /v3/api-docs → Java smoke → React / SchemaEngine	#737
Boot 4.x WebMVC	Boot4 starter / springdoc 3.0.3	OpenAPI 3.1 by default or explicitly	Both configurations passed the end-to-end matrix	#737

Enable OAS 3.1 generation explicitly on Boot 3:

springdoc:
  api-docs:
    version: OPENAPI_3_1

Boot 2 with springdoc 1.8.0 remains on OAS 3.0. Changing only the openapi string does not turn a 3.0 document into a valid 3.1 document. See the complete starter combinations in the compatibility matrix.

Product capability matrix

Unless a row says otherwise, “supported” below means the complete OpenAPI 3.1.x feature set.

Capability	OAS 3.1.x behavior	Boundary	Merged evidence
Single and multi-document loading	The entry document and controlled cross-document resources share one 3.1 parsing session	A 3.2 document does not enter the 3.1 workflow; 3.2 consumption is in the 3.2 matrix	#682, #689, #727
Document objects and Webhooks	Supports paths, components, webhooks, and 3.1 Reference Objects; at least one of the three fields must be declared	A Webhook is an inbound contract, not a regular Path request	#717
Schema dialect	OAS 3.1 Base Dialect and the standard JSON Schema Draft 2020-12 vocabularies	Arbitrary custom dialects are not assigned invented semantics	#687, #689
Field tree and models	Handles union types, boolean schemas, const, conditional/composition keywords, and dynamic references	Custom vocabularies are not executed; ordinary unknown-keyword, example, and extension payloads remain opaque, so Schema control names do not enter resource-declaration pre-scan	#692, #694, #743
Examples	Keeps authored examples and diagnoses mismatches; can generate a deterministic, budgeted fallback	Not a general JSON Schema solver	#715
Parameter debugging	Validates Path, Query, Header, and Cookie logical instances before style / explode serialization	A parameter uses either schema or one content media type; Cookie reaches preview / cURL only and is blocked before a real browser request	#716
urlencoded / multipart bodies	Handles structured fields, encoding, JSON parts, and file metadata checks	Never reads or validates uploaded file bytes	#728, #730
Request diagnostics	Schema diagnostics block first; the user may explicitly send the same snapshot for a negative test	Does not bypass browser, security, or resource policy	#696, #716, #728
Response diagnostics	Matches JSON responses by exact/range/default status and media type	Non-blocking; no response Header, Cookie, SSE, or binary validation	#713
Single-operation export	Exports a portable OpenAPI JSON closure for Path or Webhook operations when the resource graph is complete	No YAML, ZIP, multi-file, or whole-service closure export	#732, #733
Change tracking	Creates a 3.1 semantic fingerprint for a complete resource graph, isolated from 3.0 baselines	Tracks paths only, not Webhooks or field-level diffs	#736
Offline documents	HTML, Markdown, DOC, and DOCX share one immutable 3.1 snapshot	The snapshot entry reuses the shared 3.1.x version predicate; missing resources or unresolved diagnostics require cancel or explicit degraded export	#734

The complete springdoc-to-browser acceptance matrix is recorded in #737.

JSON Schema dialects and vocabularies

Default dialect

An OAS 3.1 Schema Object is a JSON Schema Draft 2020-12 dialect. When root-level jsonSchemaDialect is absent, Knife4j uses the OAS 3.1 Base Dialect:

jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base

SchemaEngine currently evaluates validation semantics only for these known dialects:

• https://spec.openapis.org/oas/3.1/dialect/base
• https://json-schema.org/draft/2020-12/schema

Standard and custom vocabularies

The standard JSON Schema 2020-12 Core, Applicator, Validation, Unevaluated, Meta-Data, Format Annotation, and Content vocabularies follow their dialect semantics. format is an annotation by default; a format string does not grant network, file, or certificate access.

Unknown extension keywords and custom-vocabulary payloads remain intact in the source document. When the SchemaEngine session succeeds, copy and portable-export surfaces retain them as well, but Knife4j defines no validation, example-generation, or field-tree semantics for them.

Resource-declaration safety pre-scan enters only known Schema-bearing locations: standalone JSON Schema roots, OAS Schema Objects, known Draft 2020-12 subschema applicators, and versioned Knife4j portable-resource containers. Ordinary data under an unknown keyword, example, or extension remains opaque. Its $id, $anchor, $dynamicAnchor, $schema, $vocabulary, $ref, and $dynamicRef values remain intact but do not participate in resource-identity, anchor, dialect, vocabulary, or reference-budget pre-scan.

A real Schema resource root that selects an unsupported $schema or declares a custom $vocabulary still receives a resource-level unsupported-dialect diagnostic and blocks actions that require complete Schema semantics. That diagnostic never falls back to an approximate dialect or executes the custom vocabulary. The implementation and regression evidence for this pre-scan boundary is #743.

External Schema resources

SchemaEngine never performs network access. The React UI first loads external $ref, $dynamicRef, and base-URI dependencies through a controlled resource graph, then passes an immutable registry to parsing, validation, export, and fingerprinting.

Authorization scope

• All external resources are denied by default. Only an exact HTTP(S) URI discovered and displayed for the current document can be authorized.
• A temporary grant lasts only for the current document generation and is lost after reload, group change, or document change.
• A remembered grant is bound to the entry document's normalized retrieval URI and content digest. The URI retains its resolved Origin, app path, and group query; it is never a host wildcard.
• Persistent records contain only a resource-URI hash, a redacted display value, and grant time—never credentials. Each document retains at most 128 grants and 128 KiB of serialized grant data.
• “Reset all local data” in Settings revokes remembered grants. “Clear request cache” does not revoke resource grants.

Requests and credentials

Resource loading uses browser CORS, GET, credentials: omit, no redirects, no referrer, and no cache. It never sends Knife4j authorization, cookies, global parameters, or business request headers. An HTTPS entry document cannot downgrade to HTTP, and a URI cannot contain userinfo.

The server must return 200, UTF-8, and a JSON or YAML media type. A cross-origin server must also allow the documentation page's Origin.

Fixed budgets

Budget	Limit
Decoded size per resource	4 MiB
Total decoded size	16 MiB
External documents	64
References	10,000
Reference depth	32
Parsed nodes per document	100,000
Parsed nodes in the graph	250,000
Schema resources	1,000
Concurrent requests	4
Request timeout	10 seconds
Load-wave timeout	30 seconds
Explicit retry	Once per resource
YAML aliases	100

Authorization, CORS, media-type, parsing, redirect, timeout, and budget failures become structured, redacted resource diagnostics. Actions that require a complete closure stay unavailable instead of silently emitting a broken result; already loaded documentation and diagnostics remain visible.

Browser debugging boundaries

An OpenAPI contract can describe behavior that browser JavaScript cannot safely send.

Case	Documentation	Browser debugger
TRACE	Displayed as an OAS 3.1 Path Item operation	Fetch cannot send it
CONNECT / TRACK	Displayed only if compatibility input reaches the debugger	Fetch cannot send them; they are not OAS 3.1 Path Item fixed fields
GET / HEAD request body	Schema, examples, and cURL can be shown	Fetch cannot send a body
Explicit Cookie parameter	Schema validation, serialized preview, and cURL can be shown	Browser scripts cannot set the Cookie header, so the real request is blocked first
Webhook	Display, field tree, offline docs, and single-operation export are available with a complete closure	Describes an inbound callback; the docs page does not initiate it
mutualTLS	Security scheme is recognized and displayed	UI never stores or injects a client certificate; configure the browser, OS, or trusted proxy
Cross-origin Schema	An authorized resource can participate in parsing	CORS and the credential-free policy still apply
Negative test override	The user may explicitly ignore the current request Schema diagnostics	Skips only the Schema block, never Fetch, auth, or resource policy

These boundaries are fixed by the browser request constraint tests, document-object #717, request-diagnostic #696, and resource-security #727 evidence.

Migrating from OpenAPI 3.0

Configure the generator to produce a real 3.1 document and review each semantic change below. Do not replace only the openapi version string.

Replace nullable with a type union

# OpenAPI 3.0
type: string
nullable: true

# OpenAPI 3.1
type: [string, "null"]

Boolean schemas

# Accept every instance
schema: true

# Reject every instance
schema: false

A boolean Schema is a complete Schema, not a missing one.

example, examples, and const

# OpenAPI 3.0 Schema
type: string
enum: [stable]
example: stable

# OpenAPI 3.1 Schema
type: string
const: stable
examples: [stable]

OpenAPI objects such as Media Type and Parameter can still have their own example / examples fields. Do not merge different object levels mechanically.

$ref siblings

# Common OpenAPI 3.0 Schema wrapper
allOf:
  - $ref: "#/components/schemas/User"
maxLength: 64

# OpenAPI 3.1 Schema composition
$ref: "#/components/schemas/User"
maxLength: 64

This rule is for a Schema Object. An OAS 3.1 Reference Object defines only summary and description as useful sibling fields; other siblings are not patches to the referenced object.

Raw binary and encoded strings

# Common OpenAPI 3.0 raw binary response
content:
  application/octet-stream:
    schema:
      type: string
      format: binary

# OpenAPI 3.1 raw binary response
content:
  image/png:
    schema:
      contentMediaType: image/png

# OpenAPI 3.1: base64 in a JSON string, not a raw body
schema:
  type: string
  contentEncoding: base64
  contentMediaType: image/png

Knife4j also preserves compatibility display for generators that still emit type: string plus format: binary. contentEncoding describes an encoded string; it is not a browser file object or raw upload body.

Webhooks and mutual TLS

webhooks:
  paymentSettled:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentEvent"
      responses:
        "204":
          description: Callback accepted
components:
  securitySchemes:
    ClientCertificate:
      type: mutualTLS

A Webhook describes an inbound call from the API provider to the API consumer; it is not a regular paths request. mutualTLS declares a security scheme, while the browser, OS, or trusted proxy owns the client certificate.

Minimal valid fixtures

The repository provides equivalent, directly downloadable fixtures:

• OpenAPI 3.1 JSON
• OpenAPI 3.1 YAML

They cover the OAS 3.1 Base Dialect, const, a nullable type union, and Media Type examples for loading, field-tree, example, and response-diagnostic checks.

Language and diagnostic parity

This page and the Chinese contract share the same version, capability, security, and migration boundaries. The existing OAS 3.1 diagnostic keys remain aligned across the Chinese, English, and Japanese React locales. The locale parity test rejects missing keys, empty translations, or mismatched interpolation variables. Changing language never changes a diagnostic code or relaxes policy.

Specifications and implementation evidence

• OpenAPI Specification 3.1.2
• OpenAPI 3.1 Schema and Base Dialect
• JSON Schema Draft 2020-12 Core
• JSON Schema Draft 2020-12 Validation
• springdoc-openapi properties
• Knife4j Next OAS 3.1 end-to-end matrix PR #737