feat: add OpenApiGeneratorV32 for OpenAPI 3.2#388
Merged
Conversation
3.2 keeps the 3.1 JSON Schema dialect (2020-12), so OpenApiGeneratorV32 reuses the 3.1 specifics and only adds the new document-structure fields: - itemSchema on media types (text/event-stream, application/jsonl, ...), converted and registered like schema when given a Zod type - itemEncoding / prefixEncoding on media types - optional response description + summary - query HTTP method on routes Requires openapi3-ts with the oas32 module (metadevpro/openapi3-ts#158). The lazy transformer cast is needed because openapi3-ts >= 4.2 added an optional $ref to SchemaObject, so 'in' no longer narrows the union.
AGalabov
reviewed
Jun 28, 2026
AGalabov
reviewed
Jul 4, 2026
AGalabov
left a comment
AGalabov
left a comment
Member
There was a problem hiding this comment.
There are some more casts that I do not like. Otherwise it is getting closer to what I envision
Contributor
Author
|
Agreed that the casts in the v3.0 and v3.1 generators weren’t necessary, removed those. I also narrowed the remaining component casts to only the raw user-provided schema and parameter buckets while keeping generated values type-checked. |
Member
|
@bookernath thank you for this contribution! 🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #385.
Adds
OpenApiGeneratorV32for generating OpenAPI3.2.xdocuments, following the subclass approach (option a) that @AGalabov agreed with on the issue.Approach
OpenAPI 3.2 keeps the 3.1 JSON Schema dialect (2020-12), so schema generation is identical to 3.1. Rather than duplicate that logic, the new generator reuses
OpenApiGeneratorV31Specificsand only layers on the document-structure fields introduced in 3.2:itemSchemaon a media type — describes each item of a sequential stream (text/event-stream,application/jsonl,application/json-seq, …). A Zod schema is converted and registered exactly likeschema(so it$refs a component); a rawSchemaObject/ReferenceObjectis passed through.itemEncoding/prefixEncodingon media typescomponents.mediaTypes, with media type$refs passed through fromcontentsummaryand an optionaldescriptionon responsesqueryHTTP method on routesDependency
Requires the
oas32module fromopenapi3-ts, added in metadevpro/openapi3-ts#158 and published in4.6.0. The dependency range is bumped^4.1.2→^4.6.0accordingly, and the lockfile is synced sonpm cistays green in CI.Notes
openapi3-ts >= 4.2added an optional$reftoSchemaObject, so'in'no longer narrows the union.itemSchemas resolve correctly.Tests
spec/v3.2.spec.tscovering the 3.2-specific behavior, reusable media type refs, webhook-only item schemas, and encoding pass-throughtsd), and prettier