Skip to content

Update OpenAPIKit to v5#875

Draft
mattpolzin wants to merge 15 commits intoapple:mainfrom
mattpolzin:update-openapi-kit-to-v5
Draft

Update OpenAPIKit to v5#875
mattpolzin wants to merge 15 commits intoapple:mainfrom
mattpolzin:update-openapi-kit-to-v5

Conversation

@mattpolzin
Copy link
Contributor

@mattpolzin mattpolzin commented Mar 9, 2026

This PR builds upon #839 to update from OpenAPIKit 4.x to OpenAPIKit 5.0. Given that, here's a more useful diff of this PR's changes:
iT0ny/swift-openapi-generator@update-openapi-kit-to-v4...mattpolzin:swift-openapi-generator:update-openapi-kit-to-v5

The work here is best reviewed one commit at a time starting with ff6cf0bd8644cdf2727f4ca22f83e7a9c133f315.

Motivation

Updating to OpenAPIKit v5.x allows the generator project to support OAS 3.2.0 features and take advantage of various other improvements to OpenAPIKit that required breaking changes to be made.

Modifications

  • Update OpenAPIKit dependency to v5.x
  • Remove code that parsed OAS 3.2.0 documents as 3.1.x documents; OpenAPIKit v5 supports OAS 3.2.0 documents natively.
  • Make changes required by move to new OpenAPIKit version (following migration guide).
  • Introduce assumeLookupOnce() to temporarily maintain the existing invariant that no entries in the Components Object are themselves references; replace all lookup() calls with assumeLookupOnce(). See the Note on this below.
  • Fix code that looked for references on JSON Schemas under the assumption that they were wrapped in OpenAPI.Reference. This assumption does not hold in OpenAPIKit v5.

NOTE on assumeLookupOnce()
The new assumeLookupOnce() function is intended to allow for gradual migration. The generator had previously used lookup() which used to look at the Components Object and either return an entry or throw. Going forward, lookup() does recursive lookup until a non-reference is found and lookupOnce() acts more like lookup() used to act -- however, lookupOnce() has a different method signature owing to the fact that it may return a reference instead of the ultimately desired object. The need for these changes arise from the fact that OpenAPIKit v5 now allows entries in the Components Object to themselves be references. This has been supported by the OpenAPI Standard for some time but OpenAPIKit only introduced support for it with v5.

Therefore, assumeLookupOnce() was added as a way to throw an error if a reference is found as an entry in the Components Object (behavior already exhibited by the generator project) but the goal should be to remove uses of assumeLookupOnce() over time and replace them with either lookupOnce() or lookup() depending on the needs of each call site. In this way, the generator project will move closer to supporting Component Object reference entries without the overhead of changing every call site all at once.

Result

Theoretically, nothing functionally changes.

Test Plan

Tests updated, swift test passing, "Compatibility test" suite passing.

@mattpolzin mattpolzin force-pushed the update-openapi-kit-to-v5 branch 2 times, most recently from 3ed2442 to b61dbf0 Compare March 9, 2026 21:07
@mattpolzin mattpolzin force-pushed the update-openapi-kit-to-v5 branch from b61dbf0 to 4e5ff88 Compare March 10, 2026 14:37
@mattpolzin mattpolzin changed the title Update openapi kit to v5 Update OpenAPIKit to v5 Mar 11, 2026
This could be squashed into 'fix code that inspects UnresolvedSchemas
for references' except for the fact that two commits tells the story
better. The first commit fixes by looking into JSONSchema.references
when they are found in UnresolvedSchemas in places where that is needed.
This second commit cleans up by flattening the UnresolvedSchema so that
we only need the inner of the two switch statements.
@mattpolzin mattpolzin force-pushed the update-openapi-kit-to-v5 branch from 4e5ff88 to 7b35cbd Compare March 11, 2026 13:46
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.

2 participants