Swift OpenAPI Generator 0.2.0 Released (OpenAPI 3.1, multiple content types)

Server Development
1

We’re happy to announce that Swift OpenAPI Generator 0.2.0 was just released!

Since it went open source in May 2023 with version 0.1.0, Swift OpenAPI Generator merged almost 100 pull requests, released 13 patch updates, and introduced support for several new features.

It wouldn’t be possible without over a dozen new contributors who filed great issues, dove into the code and opened pull requests, provided feedback on proposals, and helped prioritize which issues need to get addressed first based on real-world usage.

Highlights

In addition to many fixed bugs, here are a few notable changes in this release:

New features

  • Support multiple request and response body content types (#6, #7), including a type-safe, operation-specific Accept header (#201)
    • Now you can specify more than a single content type in a request or response body. For example, consider an API operation that returns statistics, and allows two formats: JSON and CSV.
    • In OpenAPI, that could be expressed using the following operation, and an enum with two cases will be correctly generated.
    • paths:
  /stats:
    get:
      responses:
        '200':
          content:
            application/json:
              ...
            text/csv:
              ...
    • In previous versions, the generator would only generate code for the first supported content type.
  • Add support for OpenAPI 3.1 documents, in addition to 3.0 (#219)
    • Now in addition to documents following the OpenAPI 3.0.x specification, you can also provide documents with the latest OpenAPI specification version 3.1.0.
  • Create a command plugin for generating code on-demand (#98)
    • As an alternative to generating code at build time, or using the CLI directly to generate code into your repository, you can now also invoke a Swift package command that runs the code generation and saves the files into the Sources directory, allowing you to check them into git. This is similar to the manual CLI workflow.

Other improvements

  • Reduced the minimum platform versions to allow more adopters to support earlier OS versions (#62)
    • macOS: 13 → 10.15
    • iOS: 16 → 13
    • tvOS: 16 → 13
    • watchOS: 9 → 6
  • Generate Swift deprecation annotations for types and operations deprecated in the OpenAPI document (#92)
  • Validate OpenAPI documents using OpenAPIKit’s validator, resulting in more descriptive warning and error messages (#130)
  • Support unexploded query parameters (#171)
  • Stop generating an undocumented case for enums/oneOfs (#205)
  • Stop generating empty parameter and body containers (query, headers, ...) (#235)

Accepted proposals

Breaking changes

:warning: Version 0.2.0 also contains a few breaking changes that allow the project to apply feedback on the API that would be difficult to add in a backwards compatible way. This is part of our strategy to reach version 1.0 in the coming months. See the next section for details on how to update your code.

Migrating from 0.1.x to 0.2.0

The 0.2.0 tags are now ready on the generator and runtime repositories, as well as on the URLSession, AsyncHTTPClient, Vapor, and Hummingbird transports.

This makes upgrading to 0.2.0 as easy as changing your OpenAPI-related dependencies from:

.package(url: "...", .upToNextMinor(from: "0.1.0")),

to

.package(url: "...", .upToNextMinor(from: "0.2.0")),

Due to the presence of some API-breaking changes, after you rebuild, you might encounter build errors.

Below are some of the errors you might see and how to resolve them.

  • Change: all feature flags from 0.1.13 have been enabled by default, and flags removed
    • Error: unknown feature flags
    • Fix: do not pass the feature flags anymore, they are all enabled by default in 0.2.0 and the legacy behaviors have been removed
  • Change: added support for multiple content types
    • Error: missing cases when switching over a generated request or response body enum
    • Fix: add the missing cases to handle all the documented content types
  • Change: mapping of names with special characters changed, for details see proposal SOAR-0001
    • Error: unknown type or property
    • Fix: update the name of the type or property to reflect the new escaping rules
  • Change: enabled stricter validation of OpenAPI documents using OpenAPIKit
    • Error: an OpenAPI document that was accepted by version 0.1 is rejected by 0.2
    • Fix: review the emitted error and fix up the OpenAPI document, or ask the OpenAPI author to fix the document
  • Change: string-backed enums and schemas of type oneOf do not generate an undocumented case anymore, meaning that unknown cases now lead to deserialization failing; in other words, enums and oneOfs are considered “closed” in 0.2, while they were considered “open” in 0.1
    • Error: unknown case undocumented or a new runtime error during deserialization from an “unrecognized case”
    • Fix: remove the undocumented case in code; and if you still want to use open enums and oneOfs, for example to make API evolution easier, check out this guide on how to update your OpenAPI document
  • Change: empty containers for parameters and bodies are no longer generated
    • Error: unknown type Headers, Query, ...
    • Fix: remove the code using the empty structs

What’s next

With 0.2.0 out the door, the next milestone is version 0.3.0, which is planned to adopt the new swift-http-types package for currency types and will change request and response bodies to use an asynchronous sequence of byte chunks, unlocking more streaming use cases that need to avoid buffering the whole body before reading it.

Thanks again to all our contributors and if you’d like to get involved, check out Swift OpenAPI Generator on GitHub.

11 Likes