feat(v29): Switching to OAS 3.2

[RobinTail]

squashed from #3437

required for #3479

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2c8f5ca4-5f3f-4178-8717-88f91db0f326

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch use-oas32-in-v29

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coveralls-official]

coverage: 100.0%. remained the same — use-oas32-in-v29 into make-v29

[pullfrog]

Important

The README code example still uses title and version as top-level Documentation params — these must be wrapped into info to match the new DocumentationParams interface.

Reviewed changes — switches the Documentation generator from OpenAPI 3.1 to 3.2, updating openapi3-ts to ^4.6.0, renaming SchemaObject to SchemaObjectValue, changing the Documentation constructor params (title/version → info: InfoObject, serverUrl → server: string | ServerObject | [...]), adding deprecated support to all security schemes, adding oauth2MetadataUrl and deviceAuthorization flow to OAuth2, enriching tag definitions with summary/parent/kind/externalDocs, updating SSE responses to use itemSchema, switching examples from value to dataValue, and providing migration rules.

• OAS version bump — openapi3-ts → ^4.6.0, all imports switch from oas31 to oas32, YAML output declares openapi: 3.2.0.
• Documentation constructor redesign — title and version merge into info: InfoObject; serverUrl becomes server accepting string, ServerObject, or arrays thereof.
• Security deprecated flag — Security type gains optional deprecated?: boolean, propagated to all seven security scheme depicters.
• OAuth 2.0 enhancements — new oauth2MetadataUrl option, new deviceAuthorization grant flow.
• Tag definition enrichment — depictTags accepts TagDetails objects with summary, parent, kind, and spread externalDocs.
• SSE itemSchema support — responses with content type text/event-stream use itemSchema instead of schema in MediaTypeObject.
• Examples rename — value → dataValue in ExamplesObject, matching OAS 3.2 spec.
• Migration rules — ESLint rule transforms new Documentation({ title, version, serverUrl }) → new Documentation({ info: { title, version }, server }).
• Lint guard — ESLint import restrictions block oas30/oas31 subpaths and bare SchemaObject imports from openapi3-ts.

ℹ️ Skipped "OpenAPI Documentation" test in example

The example/index.spec.ts test validates the generated YAML against the real running server. It was changed to describe.skip because the format change (value → dataValue, openapi: 3.2.0, etc.) broke the AJV validation used in that test. Consider following up with an update to the validation rather than permanently skipping.

Technical details

# Skipped OpenAPI Documentation test

## Affected sites
- `example/index.spec.ts:274` — `describe.skip("OpenAPI Documentation", ...)`

## Required outcome
- Either update the AJV validation schema to accept OAS 3.2 format changes, or create an issue to track re-enabling this test.

## Open questions for the human
- Is there a timeline for updating the AJV-based YAML validation to OAS 3.2, or should a tracking issue be filed?

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

New commit since last review — c4519709 fixes the README example (wrapping title/version into info) and stabilizes the YAML info: ordering to reduce diff noise.

• README code sample corrected — the Documentation constructor call now correctly uses info: { version, title } and server instead of the old top-level params.
• YAML ordering stabilized — example.documentation.yaml keeps title before version under info:, matching the original ordering.

The previously noted skipped test in example/index.spec.ts remains, but is a pre-existing trade-off that can be addressed in follow-up.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[RobinTail]

@pullfrog that skipped test is currently replaced by a dedicated workflow. Please assess the completeness of the OAS 3.2 support in this PR.

[pullfrog]

Reviewed changes — upgrades the Documentation class and all related code from openapi3-ts/oas31 to openapi3-ts/oas32, adding support for OAS 3.2 features while breaking the Documentation constructor API (title + version → info: InfoObject, serverUrl → server: string | ServerObject).

• OAS 3.2 type migration — all SchemaObject references replaced with SchemaObjectValue; imports switched from oas31 to oas32; openapi3-ts bumped to ^4.6.0.
• SSE itemSchema support — responses with SSE content-type now use itemSchema instead of schema in MediaTypeObject, matching the OAS 3.2 spec.
• Example format — ExampleObject.value replaced with ExampleObject.dataValue throughout generated specs.
• Security scheme deprecated — all security scheme types (basic, bearer, header, cookie, openid, oauth2, input) now propagate the deprecated flag to the generated SecuritySchemeObject.
• OAuth2 device authorization — new deviceAuthorization flow and oauth2MetadataUrl property on OAuth2Security.
• Enhanced tag objects — depictTags now accepts TagObject properties (summary, parent, kind, externalDocs) via TagDetails.
• Breaking Documentation API — serverUrl renamed to server (also accepts ServerObject); title and version merged into info: InfoObject.
• Infrastructure — ESLint rules block stale oas30/oas31 imports; migration rules auto-fix constructor calls; dedicated OAS validation workflow added; skipped e2e test properly replaced.

✅ No new issues found.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}