Swift Design

Speakeasy Swift SDKs are designed to be seamlessly integrated alongside your users' existing code:

  • Modern and idiomatic: Our Swift SDKs make use of modern and idiomatic Swift features, including async/await for concurrency, protocols, functions which throw Errors on failure, and use of the Codable (opens in a new tab) protocol for JSON (de)serialization.
  • Type-safety: Our Swift SDKs use structures and enumerated types where appropriate to ensure your users are passing the correct data to your endpoints.
  • Backwards compatible: iOS 13+ is supported, ensuring your users can target a wide range of devices and users.
  • Zero-dependency: Our Swift SDKs have zero dependencies to minimize binary size and package resolution time.
  • Well-documented: Our Swift SDKs are well-documented and can be used to generate modern and idiomatic documentation sites using Apple's DocC documentation format (opens in a new tab) that feel right at home for Swift developers.

SDK Design

Speakeasy Swift SDKs include a few main components:

  • A Client class which is the workhorse and entry-point for making requests to your API.
  • A Swift protocol (interface) which defines functions for the available operations that are exposed by your API. This API protocol is also namespaced by any tags (opens in a new tab) you define in your API specification. It is adopted by the Client class.
  • Request and response objects (defined as Swift structures) which are used to structure data for API requests and are deserialized from API responses.

Client class and API protocols

Speakeasy Swift SDKs provide a Client class for your users to interact with your API. This class uses Apple's URLSession (opens in a new tab) and URLRequest (opens in a new tab) types under the hood to construct and make the underlying network requests and handle their responses.

The SDKs transparently handle any logic required to serialize request data and deserialize responses from the server, hiding this logic and any accompanying types from them.

Your APIs available operations are defined using a Swift protocol which provides an easy reference for the available functions which your users can perform against your API. This protocol is adopted by the Client class.

Request and reponse models

Speakeasy Swift SDKs translate the data types which are required by your API operations into request objects, which are either Swift structs or enumerated types, depending on your API specification. For example, an operation that takes a set of optional parameters to query a set of pets could be implemented as a request such as:

public struct PetFilter {
  public let name: String?
  public let breed: String?
  public let minimumAge: Int?
 
  public init(name: String?, breed: String?, minimumAge: Int?) {
    self.name = name
    self.breed = breed
    self.minimumAge = minimumAge
  }
}

This allows your users to pass data to each API operation, which is then serialized into the appropriate format and included in the endpoint path, request body or headers when making the actual request to your API.

Type-safe Security and Server models

While the OpenAPI specification allows for maximum flexibility when defining server configuration and authorization and authentication strategies, Speakeasy Swift SDKs take advantage of enumerated types to ensure that your users provide you with the right data for these values at the right callsites.

For example, Speakeasy Swift SDKs trivially support any security schemes defined by your API specification:

public enum Security {
  case apiKey(String)
  case authToken(String)
}

Our Swift SDKs also provide type-safe server configuration based on your specification, including any substituted variables comprised of primitive or custom types:

public enum GlobalServers {
  /// Corresponds to `https://example.com`
  case server1
  /// Corresponds to `https://{hostname}:{port}`
  case server2(hostname: String = "localhost", port: String = "35123")
  /// Corresponds to `http://{environment}.example.com`
  case server3(environment: Environment = .staging)
}

These security and server configuration parameters are also provided at the operation level, depending on your API specification.

Enumerated Responses

The OpenAPI specification allows each of your API operations to define multiple response types, and our Swift SDKs make use of this to return enumerated values for each operation function. This allows your users to easily distinguish between and use response values returned by your API.

While these are enumerated types, Speakeasy SDKs include helper functions to access the right data when you need it:

public enum PetsResponse {
  case empty
  case pets(Shared.PetsModel)
  case error(Shared.Error)
 
  var isEmpty: Bool {
      if case .empty = self {
          return true
      } else {
          return false
      }
  }
 
  public func pets() throws -> Shared.PetsModel {
      guard case .pets(let value) = self else {
          throw PetStoreError.missingResponseData
      }
      return value
  }
 
  public func error() throws -> Shared.Error {
      guard case .error(let value) = self else {
          throw PetStoreError.missingResponseData
      }
      return value
  }
}

This allows you to easily determine whether a response is empty, or get either the pets or error model and handle any errors if the response is not of the type you expect.

Errors

Speakeasy Swift SDKs provide a comprehensive and detailed error type which provides your customers with information in cases where anything goes wrong, from constructing a request URL, to network errors, to any problems which occur when deserializing response values.

This type conforms to the Swift Error protocol, as well as providing detailed reasoning and descriptive error information.

Package Management

Speakeasy Swift SDKs support distribution using the Swift Package Manager (opens in a new tab) out-of-the-box. This makes it easy to distribute your SDKs to your customers via any hosted git repository (usually GitHub), versioned using git tags (opens in a new tab).

Coming soon: Speakeasy will soon support distribution of your Swift SDKs through CocoaPods (opens in a new tab).

Documentation

Speakeasy uses Apple's DocC documentation format (opens in a new tab) to automatically generate documentation for your SDK.

Coming Soon: The Speakeasy Generation Action (opens in a new tab) will soon allow you to automatically maintain a documentation site hosted by GitHub Pages to allow your users to easily browse documentation for your Swift SDK.

Generated Swift documentation