Swift OpenAPI Generator 1.0.0-alpha.1 (Release Candidate) Released (Multipart, base64, filtering, recursive types, and more)

We’re happy to announce that Swift OpenAPI Generator 1.0.0-alpha.1 was just released!

This is our release candidate for the 1.0 release coming in about two weeks, so please give 1.0.0-alpha.1 a try and provide feedback! There are no planned code changes for 1.0, only improvements to documentation and examples.

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

It wouldn’t be possible without over 20 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 several bug fixes, here are a few notable changes in this release:

New features

  • Base64-encoded data support (#326)
    • Allows encoding custom raw data in a JSON field by first encoding it as a base64 string.
  • Document filtering support (#319)
    • Allows only generating a subset of the provided OpenAPI document, for example by specifying a list of tags, operationIds, paths, and schemas.
    • This is especially useful when invoking or implementing only a subset of a large API, such as GitHub’s API.
    • See the proposal SOAR-0008 for examples.
  • Recursive type support (#330)
    • Allows schemas referencing themselves through a cycle, for example to represent nodes in an arbitrarily nested graph.
    • Often, metadata of file hierarchies is represented this way, and now Swift OpenAPI Generator intelligently detects cycles and breaks them by inserting a reference type under the hood, all while keeping the public API of the generated code the same.
  • Server URL template variable support (#348)
    • Server URLs in the OpenAPI document now support variables, such as https://{environment}.example.com/api, where environment can either be an arbitrary string or an enum value, for example one of development, testing, and production.
  • Multipart content type support with type safety and streaming (#366)
    • Makes working with multipart requests and responses easy by generating types for the individual documented multipart parts, but also providing access to undocumented parts.
    • Represented as an async sequence of parts, so the full multipart body never needs to be buffered in memory, allowing you to upload many large files from a tool that has a low memory limit.
    • See the proposal SOAR-0009 for examples.
  • Customizable access modifier for generated code (#393)
    • Now you can choose between public, package (the new default), and internal for the visibility of the API of the generated code. (Edit: if you see issues with the package access modifier, check out this issue.)
    • The default has been changed from public to package to protect against accidentally leaking generated APIs outside of your package.

Other improvements and bugfixes

  • Move to Swift 5.9 as the minimum tools and language version (#394)
  • Throw a descriptive error instead of crashing when encountering a malformed content type in the OpenAPI document (#339)
  • Include partial parsing errors when decoding oneOf/anyOf (#350)
  • Fix response headers that were defined inline (#355)
  • Fix a bug in path parameter ordering that could have lead to incorrect outgoing HTTP requests (#380)
  • Skip generating inferred properties, which are often indicative of a typo in the OpenAPI document (#381)
  • Generate deprecation annotations on shorthand functions (#384)
  • Explicitly disallow building the generator CLI for visionOS (#398)

Accepted proposals

Breaking changes

:warning: This release 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. See the next section for details on how to update your code.

Migrating from 0.3.x to 1.0.0-alpha.1

The 1.0.0-alpha.1 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 1.0.0-alpha.1 as easy as changing all of your Swift OpenAPI package dependencies from:

.package(url: "https://github.com/apple/swift-openapi-...", .upToNextMinor(from: "0.3.0")),

to

.package(url: "https://github.com/apple/swift-openapi-...", exact: "1.0.0-alpha.1"),

Note that due to the possibility that we will need to release further alpha versions before tagging 1.0.0, please use the “exact” version constraint temporarily.

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.3.x 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 1.0.0-alpha.1 and the legacy behaviors have been removed
  • Change: base64 encoded strings now have a dedicated type OpenAPIRuntime.Base64EncodedData
    • Error: the OpenAPIRuntime.Base64EncodedData type isn’t Swift.String
    • Fix: use the data property to access the decoded raw bytes.
  • Change: multipart content is now generated as a type-safe async sequence OpenAPIRuntime.MultipartBody
    • Error: OpenAPIRuntime.MultipartBody isn't OpenAPIRuntime.HTTPBody
    • Fix: read SOAR-0009 on how to produce and consume the sequence of parts
  • Change: Swift 5.9 is the minimum supported version
    • Error: using a Swift 5.8 toolchain doesn’t work anymore.
    • Alternative error: decl has a package access level but no -package-name was passed
    • Fix: use a Swift 5.9+ toolchain and ensure your package has // swift-tools-version: 5.9 at the top of Package.swift.
  • Change: the default visibility of generated code changed from public to package
    • Error: generated API is not visible from other packages
    • Fix: add accessModifier: public to your config file, or pass --access-modifier public to the CLI invocation

What’s next

The 1.0.0-alpha.1 release is our release candidate and the last opportunity to provide feedback that would be included in 1.0.0, which we’re targeting to release in about two weeks.

During these two weeks, please try out the alpha version to make sure that once we release 1.0.0 later in December, it will work with your project.

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

21 Likes