OpenAPI_Document

OpenAPI.Document

The root of an OpenAPI 3.0 document.

public struct Document: Equatable, CodableVendorExtendable

See OpenAPI Specification.

An OpenAPI Document can say a lot about the API it describes. A read-through of the specification is highly recommended because OpenAPIKit stays intentionally close to the naming and structure layed out by the Specification -- it goes without saying that the encoded JSON or YAML produced by OpenAPIKit conforms to the specification exactly.

Inheritance

CodableVendorExtendable, Decodable, Encodable, Equatable

Initializers

init(openAPIVersion:info:servers:paths:components:security:tags:externalDocs:vendorExtensions:)

public init(openAPIVersion: Version = .v3_0_0, info: Info, servers: [Server], paths: PathItem.Map, components: Components, security: [SecurityRequirement] = [], tags: [Tag]? = nil, externalDocs: ExternalDocumentation? = nil, vendorExtensions: [String: AnyCodable] = [:])

init(from:)

public init(from decoder: Decoder) throws

Properties

openAPIVersion

OpenAPI Spec "openapi" field.

var openAPIVersion: Version

OpenAPIKit only explicitly supports versions that can be found in the Version enum. Other versions may or may not be decodable by OpenAPIKit to a certain extent.

info

Information about the API described by this OpenAPI Document.

var info: Info

Licensing, Terms of Service, contact information, API version (the version of the API this document describes, not the OpenAPI Specification version), etc.

servers

An array of Server Objects, which provide connectivity information to a target server.

var servers: [Server]

If the servers property is not provided, or is an empty array, the default value is a Server Object with a url value of "/".

Important: If you want to get all servers mentioned anywhere in the whole document (including servers that appear in path items or operations but not at the root document level), use the `allServers` property instead.

paths

All paths defined by this API. This property maps the path of each route (OpenAPI.Path) to the documentation for that route (OpenAPI.PathItem).

var paths: PathItem.Map

components

Storage for components that need to be referenced elsewhere in the OpenAPI Document using JSONReferences.

var components: Components

Storing components here can be in the interest of being explicit about the fact that the components are always the same (such as an "Unauthorized" Response definition used on all endpoints) or it might just be practical to put things here and reference them elsewhere to cut down on the overall size of the document.

If your document is defined in Swift then this is a less beneficial way to share definitions than to just use the same Swift value multiple times, but you still might want to consider using the Components Object for its impact on the JSON/YAML structure of your document once encoded.

security

A declaration of which security mechanisms can be used across the API.

var security: [SecurityRequirement]

The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.

To make security optional, an empty security requirement can be included in the array.

Important: OpenAPIKit has a type capable of representing that: The `JSONReference`. For that reason, OpenAPIKit defines keys in security requirement objects as explicit references to entries in the Components Object instead of `String` values.

tags

A list of tags used by the specification with additional metadata.

var tags: [Tag]?

The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by Operation Objects must be declared at the document level.

Important: Each tag name in the list MUST be unique.

externalDocs

Additional external documentation.

var externalDocs: ExternalDocumentation?

vendorExtensions

Dictionary of vendor extensions.

var vendorExtensions: [String: AnyCodable]

These should be of the form: [ "x-extensionKey": <anything>] where the values are anything codable.

routes

Get all routes for this document.

var routes: [Route]

Returns

An Array of Routes with the path and the definition of the route.

allOperationIds

Retrieve an array of all Operation Ids defined by this API. These Ids are guaranteed to be unique by the OpenAPI Specification.

var allOperationIds: [String]

The ordering is not necessarily significant, but it will be the order in which each operation is occurred within each path, traversed in the order the paths appear in the document.

See Operation Object in the specifcation.

allServers

All servers referenced anywhere in the whole document.

var allServers: [OpenAPI.Server]

This property contains all servers defined at any level the document and therefore may or may not contain servers not found in the root servers array.

The servers property on OpenAPI.Document, by contrast, contains servers that are applicable to all paths and operations that do not define their own serves array to override the root array.

Important: The first `Server` encountered will be used, so if the only difference between a server at the root document level and one in an `Operation`'s override of the servers array is the description, the description of the `Server` returned by this property will be that of the root document definition.

allTags

All Tags used anywhere in the document.

var allTags: Set<String>

The tags stored in the OpenAPI.Document.tags property need not contain all tags used anywhere in the document. This property is comprehensive.

Methods

locallyDereferenced()

Create a locally-dereferenced OpenAPI Document.

public func locallyDereferenced() throws -> DereferencedDocument

A dereferenced document contains no JSONReferences. All components have been inlined.

Dereferencing the document is a necessary step toward resolving the document, which exposes canonical representations of routes and endpoints.

Important: Local dereferencing will `throw` if any `JSONReferences` point to other files or to locations within the same file other than the Components Object. It will also fail if any components are missing from the Components Object.

Throws

ReferenceError.cannotLookupRemoteReference or MissingReferenceError.referenceMissingOnLookup(name:) depending on whether an unresolvable reference points to another file or just points to a component in the same file that cannot be found in the Components Object.

encode(to:)

public func encode(to encoder: Encoder) throws

validate(using:)

Validate this OpenAPI.Document.

public func validate(using validator: Validator = .init()) throws

Call without any arguments to validate some aspects of the OpenAPI Specification not guaranteed by the Swift types in OpenAPIKit. You can create a Validator of your own, adding additional steps to the validation (or starting from scratch), and then pass that Validator to the validate(using:) method to use custom validation criteria.

Parameters

• validator: - validator: Validator to use. By default, a validator that just asserts requirements of the OpenAPI Specification will be used.

Throws

ValidationErrors if any validations failed. EncodingError if encoding failed for a structural reason.