OpenAPIKit

OpenAPIKit is used by several tools and libraries in the Swift ecosystem. These can serve as inspiration or direct solutions for common tasks:

• Code Generation: swift-openapi-generator uses OpenAPIKit to generate Swift code for interfacing with APIs.
• Vapor Integration: VaporOpenAPI demonstrates how to generate OpenAPI documentation directly from a Vapor application's routes.
• JSON:API Support: JSONAPI+OpenAPI generates OpenAPI schemas from JSON:API types.
• Declarative Documentation: The Swift Package Registry API Docs use declarative Swift code and OpenAPIKit to define documentation, which can then be encoded to YAML for tools like ReDoc.
• Semantic Diffing: OpenAPIDiff is a CLI and library that performs semantic diffing by parsing OpenAPI documents into ASTs rather than performing simple line-by-line text comparisons.

Validation is performed by crawling the OpenAPI.Document structure during the encoding process. This leads to two important constraints:

1. Validatable Protocol: You can only write validations against types that are marked with the Validatable protocol (most types in the OpenAPI namespace).
2. Encoding Behavior: Because validation follows encoding, some types behave differently:
   • URLs: These are encoded as String. You cannot write a validation directly on URL; instead, validate the String or the parent type (e.g., OpenAPI.Server).
   • Dictionary Keys: Keys (like OpenAPI.Path or OpenAPI.Response.StatusCode) are not encoded directly as objects. To validate them, you must create validations against the types that contain these dictionaries.
   • Empty Collections: If a Map or Array is empty, it may be omitted from encoding entirely. In such cases, a validation targeting the Map/Array itself might not run. To check if a collection is empty, target the parent type (e.g., target Operation to check if its responses map is empty).

Complex validation logic can be built by composing smaller Validation objects:

• lift(_:into:): Maps the current context to a new context using a KeyPath and runs a validation in that new context. Use this when the KeyPath is non-optional.
• unwrap(_:into:): Similar to lift, but if the KeyPath encounters nil, it produces a ValidationError. This is useful for asserting that an optional field must exist.
• lookup(_:): Used when a KeyPath ends in an Either<OpenAPI.Reference<T>, T>, allowing you to lift the context into validations targeting T (handling JSON References).
• all(_:...): Combines multiple validations within the same context using logical AND.
• Logical Operators: You can combine check or when arguments using && (AND) and || (OR).

// Example: Composing a validation that checks if a specific response exists and contains JSON
let contentValidation = Validation<OpenAPI.Content>(...)

let successResponseBodyContainsNameAndId = Validation(
   check: unwrap(
       \OpenAPI.Response.Map[status: 201]?.responseValue,
       into: responseBodyContainsNameAndId,
       description: "201 status response value"
    )
)

// Using logical AND to combine unwrapped checks
let postRequestAndResponsesAreValid = Validation(
    check: unwrap(
        \OpenAPI.PathItem[.post]?.requestBody?.requestValue,
        into: requestBodyContainsName
    )
    && unwrap(
        \OpenAPI.PathItem[.post]?.responses,
        into: successResponseBodyContainsNameAndId
    ),
    when: \OpenAPI.PathItem[.post] != nil
)

External dereferencing loads files referenced via external URLs into the document's Components object and converts those external references into internal ones.

To use this, you must implement the ExternalLoader protocol, providing:

1. load<T>(_ url: URL): An async function to fetch and decode the data.
2. componentKey<T>(type: T.Type, at url: URL): A function to determine the key under which the new component will be stored in the Components object.

Once implemented, call document.externallyDereference(using: loader, depth: .full).

struct ExampleLoader: ExternalLoader {
    static func load<T>(_ url: URL) async throws -> (T, [Message]) where T : Decodable {
        // Implementation to fetch and decode data
    }

    static func componentKey<T>(type: T.Type, at url: URL) throws -> OpenAPIKit.OpenAPI.ComponentKey {
        // Implementation to generate a key from the URL
    }
}

Once a document is externally dereferenced (all external files are loaded into Components), you can perform internal dereferencing to remove all remaining Reference wrappers.

1. locallyDereferenced(): Converts an OpenAPI.Document into a DereferencedDocument. In this state, types like PathItem or Operation no longer contain Either<Reference<T>, T>, but instead contain the direct type T (e.g., DereferencedParameter). This makes traversing the document much easier as you don't need to handle references.
2. resolved(): Called on a DereferencedDocument to produce a ResolvedDocument. This is a canonical form where all information (like servers, paths, and parameters) is collected into single, easy-to-query objects like ResolvedEndpoint. This is ideal for code generation or analysis, though ResolvedDocument is not currently mutable.

let document: OpenAPI.Document = ...

let resolvedDocument = try document
    .locallyDereferenced()
    .resolved()

for endpoint in resolvedDocument.endpoints {
    let path = endpoint.path
    let method = endpoint.method
    let parameters = endpoint.parameters
    let servers = endpoint.servers
}