Skip to content

feat(openapi)!: migrate to oas 0.3 and OpenAPI 3.2 - #120

Merged
Kilerd merged 1 commit into
mainfrom
fix/openapi-3-2
Sep 14, 2026
Merged

Kilerd merged 1 commit into
mainfrom
fix/openapi-3-2

Conversation

@Kilerd

@Kilerd Kilerd commented Sep 14, 2026 •

Copy link
Copy Markdown
Owner

Gotcha still emitted OpenAPI 3.0 schemas after the release of oas 0.3. This migrates the dependency and generated documents together to OpenAPI 3.2.0. For example, Option<Record> now produces anyOf: [$ref(Record), {type: null}], so null is accepted without weakening the shared Record component.

  • Centralize nullability in gotcha_core::nullable_schema; emit numeric exclusive bounds, schema examples, JSON null for Json<()>, and an unconstrained schema for raw binary bodies.
  • Adapt core, derive output, parameters, responses, and components to SchemaType / SchemaValue. Preserve boolean schemas and reference siblings, finalize references inside itemSchema / contentSchema, and leave example/default payloads untouched.
  • Keep Schematic in core and preserve standalone library, facade, and renamed-dependency support. Document source compatibility changes and the supported subset in MIGRATION.md.
  • Default documentation endpoints to JSON and Scalar. The bundled Redoc rejects 3.2; retain its explicit configuration field, disabled by default.

Validation

All 11 GitHub CI checks passed for f91cfc2.

  • Gotcha and core tests with all features and no default features; macro tests in both configurations.
  • Standalone downstream fixtures, including the check that core-only consumers do not pull in web dependencies.
  • Workspace formatting, Clippy with -D warnings, and rustdoc with -D warnings.
  • Focused regressions for recursive nullable references, enums, reference siblings, boolean/stream-item response unions, and preserving data that resembles references.
  • Exported a representative document and validated it with Python jsonschema against the official OpenAPI 3.2 schema-base. Verified acceptance/rejection of nulls, recursive values, enum values, and exclusive numeric boundaries.
  • Browser verification: Scalar loads the generated 3.2 document and displays ordinary responses and examples. On 2026-09-15, the npm latest release and existing unversioned CDN URL both resolved to @scalar/api-reference 1.68.0. An explicit 1.68.0 browser probe received and displayed two real SSE events in the request client, but the documentation still showed an itemSchema-only SSE response as “No Body”. Upstream scalar/scalar#10178 adds streaming item-schema examples and remains unmerged/unreleased; there is no stable viewer upgrade for this limitation yet. Redoc fails with “Unsupported OpenAPI Version: 3.2.0”.

This establishes the schema foundation for #86. SSE annotations and WebSocket/AsyncAPI contracts remain separate; this does not claim complete OpenAPI 3.2 model or viewer support.

Closes #119.

@Kilerd Kilerd changed the title Migrate to oas 0.3 and OpenAPI 3.2 schema semantics feat(openapi)!: migrate to oas 0.3 and OpenAPI 3.2 Sep 14, 2026
@Kilerd
Kilerd merged commit 2863e69 into main Sep 14, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[openapi] Migrate to oas 0.3 and OpenAPI 3.2 schema semantics

1 participant