feat: Add support for 3.2.0 openapi spec #54
Merged
+5,399
−592
Conversation
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
BlakeTheAwesome
force-pushed
the
blake/spec-3.2
branch
from
3ee25f8 to
f5724d6
Compare
Contributor
📊 Test Coverage ReportCurrent Coverage: Coverage Change: ✅ No change Coverage by Package
📋 Detailed Coverage by Function (click to expand)
Generated by GitHub Actions |
…uthorization flow, deprecated field, oauth2MetadataUrl, and URI-based security scheme references
TristanSpeakEasy
changed the title
TristanSpeakEasy
changed the title
danielkov
reviewed
Dec 9, 2025
| } | ||
|
|
||
| func ParseVersion(version string) (*Version, error) { | ||
| parts := strings.Split(version, ".") |
Contributor
There was a problem hiding this comment.
Nit: should this support:
1.111.1.1-beta1.1.1-xxx
Member
There was a problem hiding this comment.
for now, no I would say as the openapi versions we are working with are just x.x.x can always expand in the future if needed
TristanSpeakEasy
approved these changes
Dec 10, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
OpenAPI 3.2.0 Support
This PR implements complete support for OpenAPI Specification v3.2.0 (spec.openapis.org/oas/v3.2.0.html), maintaining full backward compatibility with OpenAPI 3.0.x and 3.1.x.
Overview
OpenAPI 3.2 introduces significant new functionality while ensuring that all existing 3.1 documents remain valid. The specification adds support for:
Implementation Summary
1. Path Item Enhancements
QUERY Method Support
queryoperation field toPathItemfor complex filtering with request bodiesCustom HTTP Methods
additionalOperationsmap field allowing arbitrary HTTP methods beyond the standard setWalkAPI to traverse additional operationswalk_test.go,bundle_test.goEnhanced Parameter Locations
querystringas valid parameter location inParameter2. Tag System Overhaul
Hierarchical Organization
parentfield toTagenabling tag hierarchiessummaryfield for concise tag descriptionskindfield with registry-backed classification (nav, badge, audience)TagKindRegistryfor extensible tag kindsMigration from Extensions
summaryreplaces vendor extensionx-displayNamex-tagGroupsto hierarchical parent relationships viaUpgrade3. Media Type Enhancements
Sequential/Streaming Data Support
itemSchemafield toMediaTypefor describing items in sequencestext/event-stream)application/jsonl,application/json-seq)Advanced Multipart Encoding
itemEncodingfield for encoding multiple array items in multipart requestsprefixEncodingarray for positional encoding rulesencoding,itemEncoding, andprefixEncodingare mutually exclusivemediatype_multipart_validate_test.go4. Security Scheme Enhancements
OAuth2 Device Authorization Flow
deviceAuthorizationflow toOAuthFlowsdeviceAuthorizationUrlfield toOAuthFlowEnhanced Metadata
oauth2MetadataUrlfield toSecuritySchemeDeprecation Support
deprecatedfield toSecuritySchemeURI-based References
$refin security scheme objects5. Discriminator Improvements
Default Mapping
defaultMappingfield toDiscriminator6. Example Object Enhancements
Structured Data Separation
dataValuefield toExamplefor schema-conformant dataserializedValuefield for HTTP message representationvaluefield (retained for backward compatibility)7. Server Object Enhancements
Server Identification
namefield toServerfor human-readable server names8. Document Identity
Self-Reference Support
$selffield toOpenAPIroot objectreference.goto use$selfwhen present9. Version Management
Improved Version Handling
internal/versionpackageMinimumSupportedVersion()andMaximumSupportedVersion()helpers10. Validation Framework
JSON Schema Dialect Updates
schema32.dialect.jsonschema32.meta.json11. Upgrade Path
Automated Migration
Upgradefunction to convert 3.0.x/3.1.x → 3.2.0x-tagGroupsvendor extension to native tag hierarchiesupgrade_test.goTesting
Comprehensive Test Coverage
All tests pass with
mise testMigration Guide
Simple Version Update
For documents already using OpenAPI 3.1, updating is straightforward:
Adopting New Features
All new features are optional and can be adopted incrementally:
Replace vendor extensions:
Add streaming support:
Use device authorization flow:
Breaking Changes
None - OpenAPI 3.2 maintains full backward compatibility with 3.1. All existing 3.1 documents remain valid 3.2 documents after version number update.
Implementation Checklist
$selffield to OpenAPI Object$selfas base URIqueryoperation method to Path Item ObjectadditionalOperationsmap to Path Item Objectsummary,parent, andkindfields to Tag Objectx-displayName→summaryx-tagGroups→ parent relationshipsin: "querystring"parameter supportitemSchemafield to Media Type ObjectitemEncodingandprefixEncodingfields to Media Type ObjectdeviceAuthorizationflow to OAuth Flows Objectoauth2MetadataUrlto Security Scheme Objectdeprecatedfield to Security Scheme ObjectdefaultMappingto Discriminator ObjectdataValueandserializedValueto Example Objectvaluefield in Example Objectnamefield to Server Objectsummaryfield to Response ObjectReferences