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.

A document is decoded in the normal fashion for Codable types:

let data: Data = ...
let document = try JSONDecoder().decode(OpenAPI.Document.self, data)

At this point, all of the information exposed by the decoded documentation is available via OpenAPIKit types that largely follow the structure and naming conventions of the specification.

If the documentation exists within a single file (no JSON references to other files) and there are no cyclic JSON references, you can dereference the documentation to remove the need to follow JSON references while traversing the documentation.

let dereferencedDocument = try document.locallyDereferenced()

See the documentation on OpenAPI.Document.locallyDereferenced() for more.

At this point all references have been removed and replaced with inline documentation components. You can "resolve" the documentation to get an even more concise representation; this is no longer an OpenAPI representation, but rather an alternative view OpenAPIKit provides that can make analyzing and traversing documentation substantially easier for certain use-cases.

let resolvedDocument = dereferencedDocument.resolved()

See the documentation on DereferencedDocument.resolved() for more.

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.

public 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.

public 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.

public 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 "/".

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).

public var paths: PathItem.Map

See the routes property for an array of equatable Path/PathItem pairs.

components

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

public 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.

public 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.

tags

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

public 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.

externalDocs

Additional external documentation.

public var externalDocs: ExternalDocumentation?

vendorExtensions

Dictionary of vendor extensions.

public 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.

public 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.

public 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.

public 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.

allTags

All Tags used anywhere in the document.

public 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

filteringPaths(with:)

Create a new OpenAPI Document with all paths not passign the given predicate removed.

public func filteringPaths(with predicate: (OpenAPI.Path) -> Bool) -> OpenAPI.Document 

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.

Throws

ReferenceError.cannotLookupRemoteReference or ReferenceError.missingOnLookup(name:​key:​) 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 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.