JSONReference

JSONReference

A reference following the JSON Reference specification.

public enum JSONReference<ReferenceType: ComponentDictionaryLocatable>

These references are formatted like

$ref: filename.yml#/path/to/something

The filename is omitted for internal references and the path is not required for external references.

The intention, as prescribed by the OpenAPI specification, is for this type to conform to the logic in the JSON Reference spec.

A common reason to use JSONReferences is to refer to something in the OpenAPI Components Object. There are two easy ways to create this kind of reference.

Which you use depends on your specifc needs. The reference(named:ofType:) method will guarantee that the thing you are referencing exists in the Components Object (or else the method will throw an error). The component(named:) constructor by contrast will not guarantee that the component you are referencing currently exists in the Components Object. The lack of safety might be beneficial or necessary depending on whether you have the Components Object built out and available at the time and location where you need to create a reference.

Regardless of how you create your reference, internal references to things in the Components Object will be validated when you call validate() on an OpenAPI.Document.

Inheritance

Decodable, Encodable, Equatable, Hashable, LocallyDereferenceable, _OpenAPIReference

Initializers

init(from:)

public init(from decoder: Decoder) throws

Enumeration Cases

`internal`

The reference is internal to the file.

case `internal`(: InternalReference)

external

The reference refers to another file.

case external(: URL)

Properties

isInternal

true for internal references, false for external references (i.e. to another file).

var isInternal: Bool

isExternal

true for external references, false for internal references.

var isExternal: Bool

name

Get the name of the referenced object. This method returns optional because a reference to an external file might not have any path if the file itself is the referenced component.

var name: String?

absoluteString

The absolute value of an external reference's URL or the path fragment string for a local reference as defined in RFC 3986.

var absoluteString: String

Methods

component(named:)

Reference a component of type ReferenceType in the Components Object.

public static func component(named name: String) -> Self

Example:

JSONReference<JSONSchema>.component(named: "greetings")
// encoded string: "#/components/schemas/greetings"
// Swift: `document.components.schemas["greetings"]`

`internal`(path:)

Reference a path internal to this file but not within the Components Object This is likely not what you are looking for. It is advisable to store reusable components in the Components Object.

public static func `internal`(path: Path) -> Self

Important: The path does not contain a leading '\#'. Start with the root '/'.

encode(to:)

public func encode(to encoder: Encoder) throws