Protocol

ServerTransport

A type that registers and handles HTTP operations.

protocol ServerTransport

Overview

Decouples the HTTP server framework from the generated server code.

Choose between a transport and a middleware

The ServerTransport and ServerMiddleware protocols look similar, however each serves a different purpose.

A transport abstracts over the underlying HTTP library that actually receives the HTTP requests from the network. An implemented handler (a type implemented by you that conforms to the generated APIProtocol protocol) is generally configured with exactly one server transport.

A middleware intercepts the HTTP request and response, without being responsible for receiving the HTTP operations itself. That’s why middlewares take the extra next parameter, to delegate calling the handler to the transport at the top of the middleware stack.

Use an existing server transport

Instantiate the transport using the parameters required by the specific implementation. For example, using the server transport for the Vapor web framework, first create the Application object provided by Vapor, and provided it to the initializer of VaporTransport:

let app = Vapor.Application()
let transport = VaporTransport(routesBuilder: app)

Implement a new type that conforms to the generated APIProtocol, which serves as the request handler of your server’s business logic. For example, this is what a simple implementation of a server that has a single HTTP operation called checkHealth defined in the OpenAPI document, and it always returns the 200 HTTP status code:

struct MyAPIImplementation: APIProtocol {
    func checkHealth(
        _ input: Operations.checkHealth.Input
    ) async throws -> Operations.checkHealth.Output {
        .ok(.init())
    }
}

The generated operation method takes an Input type unique to the operation, and returns an Output type unique to the operation.

Note

You use the Input type to provide parameters such as HTTP request headers, query items, path parameters, and request bodies; and inspect the Output type to handle the received HTTP response status code, response header and body.

Create an instance of your handler:

let handler = MyAPIImplementation()

Create the URL where the server will run. The path of the URL is extracted by the transport to create a common prefix (such as /api/v1) that might be expected by the clients.

try handler.registerHandlers(
    on: transport,
    serverURL: URL(string: "/api/v1")!
)

Start the server by following the documentation of your chosen transport:

try await app.execute()

Implement a custom server transport

If a server transport implementation for your preferred web framework doesn’t yet exist, or you need to simulate rare network conditions in your tests, consider implementing a custom server transport.

Define a new type that conforms to the ServerTransport protocol by registering request handlers with the underlying web framework, to be later called when the web framework receives an HTTP request to one of the HTTP routes.

In tests, this might require using the web framework’s specific test APIs to allow for simulating incoming HTTP requests.

Implementing a test server transport is just one way to help test your code that integrates with your handler. Another is to implement a type conforming to the generated protocol APIProtocol, and to implement a custom ServerMiddleware.

Topics

Instance Methods

func register((HTTPRequest, HTTPBody?, ServerRequestMetadata) async throws -> (HTTPResponse, HTTPBody?), method: HTTPRequest.Method, path: String) throws
Registers an HTTP operation handler at the provided path and method.