apigenie-generator client swift
Experimental · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate a Swift package calling the operations of an OpenAPI document, for iOS, macOS, tvOS, watchOS and Linux apps.
(experimental, outside the 1.0 compatibility promise) The generated code isn’t yet built and run against a live API by the conformance suite, so its types and methods can still change.
client swiftsays so in its--helpand on the first line it prints, on the standard error. See the experimental commands.
Usage
apigenie-generator client swift [...OPTIONS] INPUT_FILE
Description
The generator writes a Swift package with one library target. Its code uses Foundation only: the package has no dependencies.
| File | Contents |
|---|---|
Package.swift |
tools version 6.0, the platforms (iOS 16, macOS 13, tvOS 16, watchOS 9) and a library product of the module |
.swift-format |
the swift-format settings the generated code follows (swift format lint) |
Sources/<Module>/Client.swift |
Server, Credentials and Client, with an async method per operation |
Sources/<Module>/Operations.swift |
per operation, the enum of its responses, the structs of their headers and the enums of bodies of several media types |
Sources/<Module>/Models.swift |
the types of the component schemas the operations use, and of their inline schemas |
Sources/<Module>/Runtime/*.swift |
the transport, requests and errors, JSON coding, parameter styles, streams, multipart bodies, validation, Nullable, CalendarDate, Indirect, JSONValue |
The module is named after the document’s title followed by Client (Carpet Express Shipping API gives CarpetExpressShippingAPIClient; APIClient when the title gives no name), unless
--package-name or package names it.
let client = Client(server: .production, credentials: .apiKey(apiKey))
switch try await client.getShipment(shipmentID: "shp_123") {
case .ok(let body, let headers):
print(body, headers.eTag)
case .notFound(let problem):
print(problem.title)
case .notModified:
break
}
Methods
Every operation is a method of Client, named after its operationId. Its arguments are the
path parameters, the body (body:, nil by default when optional), the required query, header
and cookie parameters, then the optional ones defaulting to nil, in document order. It returns
the operation’s response enum, with a case per documented status:
public func createShipment(
body: ShipmentCreate,
idempotencyKey: UUID? = nil,
prefer: CreateShipmentPrefer? = nil,
xRequestID: String? = nil
) async throws -> CreateShipmentResponse
public enum CreateShipmentResponse: Sendable {
/// `201`: Shipment booked.
case created(body: Shipment, headers: CreateShipmentCreatedHeaders)
/// `400`: The request could not be parsed.
case badRequest(Problem)
// ... 202, 401, 403, 409, 422, 429
/// `5XX`: A carrier or Carpet Express itself is unavailable.
case serverError(statusCode: Int, body: Problem, headers: CreateShipmentServerErrorHeaders)
}
- A case holds the body of its status and, when the response declares headers, a struct of them;
ranges (
5XX) anddefaultalso hold the status code. A status with several media types holds an enum of them (.pdf(Data),.json(LabelEnvelope)), chosen by the response’sContent-Type. - A status the document doesn’t list throws
ClientError.undocumentedStatuswith the status, the headers and the body; a body or header that can’t be read throwsClientError.invalidResponse, and a request that can’t be written (a null required path parameter, an invalid URL) throwsClientError.invalidParameter. - A request body of several media types is an enum with a case per media type
(
UpdateShipmentRequestBody.mergePatchJSON(ShipmentPatch)). - JSON bodies are checked against their schemas before they are sent while
client.validatesRequestsistrue(the default,validate_requests): a body that breaks one throwsClientError.invalidRequestwith the constraints it breaks.validatesResponses(validate_responses) checks response bodies the same way. - Parameters are written in their style and
explodemode:simple,labelandmatrixpath parameters,form,spaceDelimited,pipeDelimitedanddeepObjectquery parameters,allowReserved, headers and cookies. Parameters described withcontentare sent as JSON. - Methods set
Acceptto the media types of the documented responses. - Operations marked
x-internal: true(on the operation or its path) are left out, unlessinternal_operationsis set. Deprecated operations are marked@available(*, deprecated).
Streams
text/event-stream, application/jsonl and application/json-seq responses are
AsyncThrowingStreams of their items, typed by the media type’s itemSchema (OpenAPI 3.2;
x-itemSchema in 3.0 and 3.1 documents):
if case .ok(.eventStream(let events)) = try await client.getTrackingEvents(shipmentID: id) {
for try await event in events {
print(event.id ?? "", event.data)
}
}
- Server-sent events are
ServerSentEventvalues whosedatais decoded as thecontentSchemaof theitemSchema’sdataproperty, or kept as aString. - On Apple platforms the items arrive as the server sends them (
URLSession.bytes(for:)). On Linux, whose Foundation has nobytes(for:),URLSessionTransportreads the whole body first. - JSON Lines and JSON text sequence request bodies are arrays of their items.
Multipart bodies
multipart/form-data bodies of object schemas are structs with a property per part. Binary parts
(format: binary, or contentMediaType in 3.1 and 3.2) are MultipartFile values (data, file
name and media type), arrays of them [MultipartFile]. Object parts, and parts whose encoding has
a JSON contentType, are sent as JSON; other parts as text, a part per item of arrays.
Servers
Server has a static property per server of the document, named after its name or
description (.production, .sandbox; server1 when neither gives a name), with the default
values of its variables. Client sends to the first one unless server: says otherwise; without
servers in the document, server: is required. Server(url:) makes any other. Operations with
servers of their own (on the operation or its path) are sent there unless usesOperationServers
is false, e.g. for a test server or a proxy.
Security
Credentials has a property per security scheme of the document, and a function making
credentials of that scheme alone:
| Scheme | Property | Sent as |
|---|---|---|
apiKey in a header, the query or a cookie |
String? |
the header, query parameter or cookie |
http basic |
BasicCredentials? |
Authorization: Basic ... |
http bearer |
String? |
Authorization: Bearer ... |
oauth2, openIdConnect |
TokenProvider?, an async closure returning the access token |
Authorization: Bearer ... |
mutualTLS |
Bool, set when the transport presents the certificate |
URLSessionTransport(clientCertificate:) (Apple platforms) |
A request gets the credentials of the first alternative of its operation’s security
requirements whose schemes all have credentials; without one, the method throws
ClientError.missingCredentials. An operation with security: [] gets none.
Transport
Client sends requests through an HTTPTransport (one async throws method, send(_:)),
URLSessionTransport by default. A transport of your own can add retries, logging or a test
double.
Stability
Experimental, since 0.12.0.
What you depend on
- Swift 6.0 or later, in the Swift 6 language mode (strict concurrency).
- Swift Package Manager (
swift build), which readsPackage.swift(tools version 6.0). - Foundation, and FoundationNetworking on Linux. No package dependencies.
- iOS 16, macOS 13, tvOS 16 or watchOS 9 on Apple platforms.
Features
| Feature | Support |
|---|---|
| Authentication schemes | yes: API keys, HTTP basic and bearer, OAuth 2 and OpenID Connect tokens, mutual TLS |
| Streaming | partial: server-sent events, JSON Lines and JSON text sequences arrive as sent on Apple platforms; on Linux the body is read whole first |
| Pagination | no |
| File upload | yes: multipart bodies and binary bodies |
| Enums | yes, with unknown(String) for values the document doesn’t list |
| Discriminators | yes, with mapping and defaultMapping |
| Nullable | yes: Nullable<T>? tells missing, null and set values apart |
| Errors | yes: a case per documented status, typed ClientErrors |
| Retries | no: an HTTPTransport of your own can retry |
Type mapping
| Schema | Swift |
|---|---|
| object | public struct that is Codable, Hashable, Sendable and Validatable, with a memberwise initializer |
| optional property | T?, left out when encoding nil |
| optional nullable property | Nullable<T>?: nil when missing, .null when null |
| required nullable property | T?, written as null |
| string or integer enum | an enum with a case per value and unknown(String) (unknown(Int)), or without it with unknown_enum_cases: false |
oneOf, anyOf |
an indirect enum with a case per variant; with a discriminator, the variant its property selects, else the first variant the value decodes as |
allOf |
the properties merged into one struct |
prefixItems |
a struct with a property per position (item0, item1), coded as an array |
additionalProperties, patternProperties |
[String: V], or additionalProperties of the struct |
integer |
Int; Int8 … Int64, UInt … UInt64 by format; Int64 for double-int, unixtime |
number |
Double, Float, Decimal (format: decimal, decimal128) |
date-time, date, uuid, uri and url |
Date, CalendarDate, UUID, URL |
byte, binary |
Data |
| any value | JSONValue |
| recursive struct | the property held through @Indirect |
Every struct, union and tuple has validate(), which checks lengths, patterns, numeric limits,
item counts, unique items, const, enum, formats, if/then/else, dependentRequired,
dependentSchemas and the oneOf/anyOf groups of required properties, and throws a
ValidationError listing the constraints a value breaks with JSON pointers to them.
Extensions
| Extension | Effect |
|---|---|
x-swift-name |
name of the type of a schema, or of the property of a property |
x-enum-varnames, x-enumNames |
names of the enum cases |
x-enum-descriptions |
documentation of the enum cases |
x-apigenie.codegen.name |
name of the type of a component schema, when it has no x-swift-name |
x-apigenie.codegen.action-name |
name of the method of an operation without an operationId (with the default action_naming) |
x-apigenie.codegen.disabled |
true on an operation or its path item leaves the operation out |
x-internal |
true on an operation or its path item leaves the operation out, unless internal_operations is set |
x-defaultMapping |
defaultMapping of a discriminator in OpenAPI 3.0 and 3.1 documents |
x-itemSchema |
itemSchema of a media type in OpenAPI 3.0 and 3.1 documents |
Options
-c, –config
Path to the configuration file to use. See the “Configuration” section for more information.
–overlay OVERLAY
Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those
listed under commands.generate.client_swift.overlay in the configuration file.
–strict
Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated) instead of a warning.
–no-config
Doesn’t look for apigenie.yaml (or .apigenie.yaml) in the current directory and its parents up
to the root of the repository.
–json
Prints one JSON document on the standard output (formatVersion, command, exitStatus,
messages) instead of the messages.
-o, –output
Directory where the package is generated.
–package-name
Name of the Swift module, its library product and the package. Defaults to the document’s title
followed by Client.
–package-version
Ignored: Swift packages take their versions from Git tags.
-p, –property NAME=VALUE
Sets a generator option (see below), e.g. -p validate_responses=true. Options given on the
command line take precedence over the configuration file. Lists are comma-separated
(-p include_tags=shipments,rates).
Configuration
version: '1.0'
commands:
generate:
client_swift:
package: CarpetExpress
validate_responses: true
exclude_tags: [internal]
| Option | Type | Default | Description |
|---|---|---|---|
package |
string | the document’s title followed by Client |
Name of the module, its library product and the package; also set by --package-name. |
include_tags |
list of strings | Generates only the operations with one of these tags. | |
exclude_tags |
list of strings | Skips the operations with one of these tags. | |
skip_prune |
boolean | false |
Keeps the component schemas that no generated operation uses. |
internal_operations |
boolean | false |
Also generates the operations marked x-internal: true. |
validate_requests |
boolean | true |
The default of Client.validatesRequests: request bodies are checked before they are sent. |
validate_responses |
boolean | false |
The default of Client.validatesResponses: response bodies are checked. |
unknown_enum_cases |
boolean | true |
Enums get an unknown case for values the document doesn’t list. |
initialisms |
list of strings | Words written in one case in identifiers, besides ID, URL, HTTP, JSON and the other common initialisms. |
|
action_naming |
list of id, extension, url |
id, extension, url |
Where method names come from, in order of preference. |
Exit status
0 when the package was generated; 2 when the options, the configuration, an overlay or the input
document can’t be used (with --strict, also when an overlay action selects nothing). See
apigenie-generator.
Limitations
- What the conformance fixture doesn’t cover is listed under Verification; callbacks, webhooks and links are out of scope there.
validate()skips patterns Swift’sRegexcan’t compile andunevaluatedPropertiesother thanfalse. It checksif/then/elseanddependentSchemasonly when their schemas userequiredand theconstandenumof properties.format: decimalnumbers are decoded byJSONDecoder, which reads them throughDoubleon Apple platforms before macOS 15 and iOS 18.- A
oneOfwithout a discriminator decodes as its first variant that decodes, even when another one matches too. - Types of the standard library, Foundation, the runtime and the client (
Data,Error,ValidationError,Client,Credentials,Server, …) are reserved: schemas with these names get types withModelafter their names, e.g.ErrorModel. - The input must be an OpenAPI 3.0, 3.1 or 3.2 document or a Swagger 2.0 document (see
Swagger 2.0 input); bundle documents referencing
other files with
apigenie bundle.
Verification
The codegen conformance suite runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.
This target's support tier is Experimental. It isn't run at every level yet. It is outside the 1.0 compatibility promise: its options and the shape of its output can change, or it can go away, in a minor release.
| Results | Level 1 | Level 2 | Level 3 |
|---|---|---|---|
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 37 supported, 0 not yet | ✓ pass (Swift version 6.0.3 (swift-6.0.3-RELEASE)) | ✓ 37 of 37 operations pass (swift) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 37 supported, 0 not yet | runs before a release | runs before a release |