Swift OpenAPI Generator Reaches 1.0

Write for InfoQ

Open-sourced six months ago, the Swift OpenAPI Generator is now stable. Version 1.0 brings new features and a simplified API.

The Swift OpenAPI Generator is an open-source Swift package plugin that can be used to automatically generate the code required to access or implement HTTP endpoints described using OpenAPI. The plugin can be run at build-time, thus ensuring the generated code is always up-to-date with the latest OpenAPI description of the API, and is able to generate code to make API calls as well as stubs to integrate with the corresponding server-side services.

Among the new features brought by release 1.0 are the adoption of AsyncSequence to enable JSON event streams and large payloads without buffering; support for type-safe common content types, including JSON, multipart, URL-encoded, etc; and better decoupling of generated code thanks to flexible abstractions on client- and server-side.

On the client-side, the Swift OpenAPI Generator creates classes that can work with any HTTP framework supporting the ClientTransport protocol. On the server-side, any web framework conforming to the ServerTransport protocol is compatible with it.

While striving to ensure API stability, chances are that after revising an OpenAPI specification, the generated code will break your program and you will need to fix its usage. This may affect both client- and server-side code.

Generally speaking, when you modify an OpenAPI doc to add a new response, add a new content type, remove a required property, or rename a schema, your Swift code will require changes to work with newly generated code.

For example, when adding a new response to an existing operation, or a new content type to an existing response, the Swift OpenAPI Generator will create a new enum case to handle that. This means all switch statements using that enum will need to explicitly address that new case to pass the compiler check, unless they implement a default case. Of course, a default case will make sure your program will not break at compile time, but this does not necessarily mean it will produce the correct outcome.

A somewhat different case is when adding a new property to an existing schema. This kind of change will be non-breaking if your code does not capture the init method signature for the corresponding struct, which necessarily changes to account for the new property. As a general rule, you should never include the generated code, which includes schema initializers, in your public APIs.

The Swift OpenAPI Generator 1.0 is compatible with OpenAPI 3.0 and 3.1 specifications and can be available on the Swift Package Index.

Related Topics:

• Development
• Swift
• Apple
• MacOS
• Mobile
• iOS
• Open Source
• Open API Initiative

We protect your privacy.