Skip to content

Conversation

@mattpolzin
Copy link
Owner

@mattpolzin mattpolzin commented Nov 13, 2025

Fixes #377

Breaking Changes

Components Object

There are changes for the OpenAPIKit30 module (OAS 3.0.x specification) in
this section.

Entries in the Components Object's responses, parameters, examples,
requestBodies, headers, securitySchemes, links, and callbacks
dictionaries have all gained support for references. Note that pathItems and
schemas still do not support references (per the specification), though
schemas can be JSON references by their very nature already.

This change fixes a gap in OpenAPIKit's ability to represent valid documents.

If you are using subscript access or lookup() functions to retrieve entries
from the Components Object, you do not need to change that code. These
functions have learned how to follow references they encounter until they land
on the type of entity being looked up. If you want the behavior of just
doing a regular lookup and passing the result back even if it is a reference,
you can use the new lookupOnce() function. The existing lookup() functions
can now throw an error they would never throw before: ReferenceCycleError.

Error message phrasing has changed subtly which is unlikely to cause problems
but if you have tests that compare exact error messages then you may need to
update the test expectations.

If you construct Components in-code then you have two options. You can swap
out existing calls to the Components init() initializer with calls to the
new Components.direct() convenience constructor or you can nest each component
entry in an Either like follows:

// BEFORE
Components(
  parameters: [
    "param1": .cookie(name: "cookie", schema: .string)
  ]
)

// AFTER
Components(
  parameters: [
    "param1": .parameter(.cookie(name: "cookie", schema: .string))
  ]
)

If your code uses the static openAPIComponentsKeyPath variable on types that
can be found in the Components Object (likely very uncommon), you will now need
to handle two possibilities: the key path either refers to an object (of generic
type T) or it refers to an Either<OpenAPI.Reference<T>, T>.

@mattpolzin mattpolzin force-pushed the feature/377/support-refs-in-components branch from 163f277 to e83da2a Compare November 17, 2025 17:14
@mattpolzin mattpolzin marked this pull request as ready for review November 18, 2025 14:42
@mattpolzin mattpolzin merged commit be89ec8 into release/5_0 Nov 18, 2025
27 of 29 checks passed
@mattpolzin mattpolzin deleted the feature/377/support-refs-in-components branch November 18, 2025 15:02
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