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

paths

All routes supported 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?

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]

See Operation Object in the specifcation.

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.

Methods

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.