Skip to content

Add missing lookupOnce variants #483

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattpolzin merged 1 commit into from
Mar 10, 2026
+87 −18
Merged

Add missing lookupOnce variants #483

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 87 additions & 18 deletions Sources/OpenAPIKit/Components Object/Components+JSONReference.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,8 +167,10 @@ extension OpenAPI.Components {
/// object will have its `summary` and/or `description` overridden by that of the reference.
/// This only applies if the referenced object would normally have a summary/description.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)`
Expand Down Expand Up @@ -207,8 +209,10 @@ extension OpenAPI.Components {
/// object will have its `summary` and/or `description` overridden by that of the reference.
/// This only applies if the referenced object would normally have a summary/description.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)` or
Expand Down Expand Up @@ -239,8 +243,10 @@ extension OpenAPI.Components {
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)`
Expand All @@ -262,8 +268,10 @@ extension OpenAPI.Components {
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)` or
Expand Down Expand Up @@ -301,8 +309,10 @@ extension OpenAPI.Components {
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)`
Expand Down Expand Up @@ -337,8 +347,10 @@ extension OpenAPI.Components {
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)` or
Expand Down Expand Up @@ -399,8 +411,10 @@ extension OpenAPI.Components {
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)` or
Expand All @@ -414,22 +428,52 @@ extension OpenAPI.Components {
}
}

/// Pass an `Either` with a reference or a component. `lookupOnce()` will
/// return the component value if it is found in the Components Object.
/// That value may itself be a reference. If you want to look things up in
/// the components object recursively use `lookup()`.
///
/// If you want to look something up without throwing, you might want to use the subscript
/// operator on the `Components`.
///
/// If you also want to fully dereference the value in question instead of
/// just looking it up see the various `dereference` functions on this type
/// for more information.
///
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)`
public func lookupOnce<ReferenceType: ComponentDictionaryLocatable>(_ maybeReference: Either<OpenAPI.Reference<ReferenceType>, ReferenceType>) throws -> Either<OpenAPI.Reference<ReferenceType>, ReferenceType> {
switch maybeReference {
case .a(let reference):
return try lookupOnce(reference.jsonReference)
case .b(let value):
return .b(value)
}
}

/// Lookup schema in the `Components`. If the JSONSchema is not a
/// reference, it will be returned as-is. If it is a reference, it will be
/// looked up in the components if it refers to a components entry.
///
/// This function will follow subsequent refernences found within the
/// `Components` as long as no cycles are encountered.
///
/// If you want to look something up without throwing, you might want to use the subscript
/// operator on the `Components`.
/// If you want to look something up without throwing, you might want to
/// use the subscript operator on the `Components`.
///
/// If you also want to fully dereference the value in question instead
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Looking up an external reference (i.e. one that points to another file)
/// is not currently supported by OpenAPIKit and will therefore always throw an error.
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)` or
Expand All @@ -441,6 +485,31 @@ extension OpenAPI.Components {
return try lookup(reference)
}

/// Lookup schema in the `Components`. If the JSONSchema is not a
/// reference, it will be returned as-is. If it is a reference, it will be
/// looked up in the components if it refers to a components entry.
///
/// If you want to look something up without throwing, you might want to
/// use the subscript operator on the `Components`.
///
/// If you also want to fully dereference the value in question instead
/// of just looking it up see the various `dereference` functions
/// on this type for more information.
///
/// - Important: Loading an external reference (i.e. one that points to
/// another file) is done via `externallyDereferenced(with:)` functions
/// available on most types; attempting to lookup an external reference
/// will `throw`.
///
/// - Throws: `ReferenceError.cannotLookupRemoteReference` or
/// `ReferenceError.missingOnLookup(name:,key:)`
public func lookupOnce(_ schema: JSONSchema) throws -> JSONSchema {
guard case .reference(let reference, _) = schema.value else {
return schema
}
return try lookupOnce(reference).flattenToJsonSchema()
}

/// Create an `OpenAPI.Reference`.
///
/// - Throws: If the given name does not refer to an existing component of the given type.
Expand Down