Skip to content

0026-swift-openapi-generator.md

Latest commit

 

History

History
114 lines (84 loc) · 10.7 KB

0026-swift-openapi-generator.md

File metadata and controls

114 lines (84 loc) · 10.7 KB
Raw

Swift OpenAPI Generator

Package Description

OpenAPI is an open specification for documenting HTTP APIs.

Swift OpenAPI Generator is a Swift package plugin that can generate the ceremony code required to make API calls, or implement API servers.
Package Name swift-openapi-generator
Module Name OpenAPIGenerator (build plugin), swift-openapi-generator (CLI)
Proposed Maturity Level Sandbox
License Apache-2.0
Dependencies OpenAPIKit (v3.0.0-alpha.9), Yams (v4, v5), swift-argument-parser (v1), swift-algorithms (v1), swift-syntax (v508.0.1+), swift-format (v508.0.1+), swift-docc-plugin (v1), swift-openapi-runtime (v0.1.0+)

Code generated by Swift OpenAPI Generator uses common abstractions from a runtime library, called swift-openapi-runtime:
Package Name swift-openapi-runtime
Module Name OpenAPIRuntime
Proposed Maturity Level Sandbox
License Apache-2.0
Dependencies swift-docc-plugin (v1)

And since Swift OpenAPI Generator decouples the concrete HTTP library from the generated code, and uses the "API package" approach that swift-log, swift-metrics, and swift-distributed-tracing follow, we are also proposing to include two concrete transport implementations maintained by the authors of Swift OpenAPI Generator.
Package Name swift-openapi-urlsession
Module Name OpenAPIURLSession
Proposed Maturity Level Sandbox
License Apache-2.0
Dependencies swift-docc-plugin (v1), swift-openapi-runtime (v0.1.0+)
Package Name swift-openapi-async-http-client
Module Name OpenAPIAsyncHTTPClient
Proposed Maturity Level Sandbox
License Apache-2.0
Dependencies swift-docc-plugin (v1), swift-openapi-runtime (v0.1.0+), async-http-client (v1), swift-nio (v2)

We expect authors of other transports to also pitch their transport implementations for SSWG incubation.

Introduction

OpenAPI is a specification for documenting HTTP services. An OpenAPI document is written in either YAML or JSON, and can be read by tools to help automate workflows, such as generating the necessary code to send and receive HTTP requests.

Swift OpenAPI Generator is a SwiftPM plugin that takes an OpenAPI document and generates either the client code to perform HTTP calls or the server code to handle those calls. The generated code translates between a type‑safe representation of each operation’s input and output, and the underlying HTTP request and response.

Swift OpenAPI Generator is not tied to a specific client or server HTTP library; it allows plugging in custom libraries that provide the bridging code between the abstract representation defined in our runtime library, and the specific HTTP library. To learn more, check out the documentation.

Swift OpenAPI Generator was open sourced in May 2023 in a pre-1.0 state and continues development fully in the open. It was announced in a blog post on Swift.org and presented in Meet Swift OpenAPI Generator at WWDC 2023.

Motivation

OpenAPI is a widely adopted specification of describing HTTP services, and the Swift ecosystem should have a fully supported set of tools for generating client and server code from it. On the client side, it allows app developers to quickly bootstrap a Swift client to talk to any arbitrary service, and on the server side, it allows more Swift developers to write servers, as the glue code between the underlying server and the actual business logic is generated for them.

The Swift server ecosystem already solved this problem for gRPC with grpc-swift, but any credible server language also requires support of HTTP REST services, which OpenAPI provides.

One piece of evidence that such a tool was missing in the ecosystem was the not-so-uncommon pattern of using grpc-swift, but instead of vending its gRPC API to users, putting an HTTP-gRPC translating proxy in front of it, and actually provide an HTTP REST API to users. Providing first class OpenAPI support allows server developers to use OpenAPI tools for providing an HTTP REST API, and gRPC tools for providing a gRPC API. That's what each tool was designed to do well.

Proposed solution

For a concrete end-to-end example of using an OpenAPI document with a generated client and server, check out the Swift.org announcement and the WWDC 2023 session.

Detailed design

  • swift-openapi-generator (docs) is the package plugin, which consumes an OpenAPI document, and generates Swift files. It uses a command-line tool of the same name under the hood, which can be used directly by adopters in cases where a build plugin isn't appropriate.
  • swift-openapi-runtime (docs) is a library package that provides the HTTP currency types, the transport and middleware abstractions, and helper functions used by the generated code.
  • swift-openapi-urlsession (docs) is a library package that provides a concrete implementation of a ClientTransport that uses Foundation's URLSession API under the hood.
  • swift-openapi-async-http-client (docs) is a library package that provides a concrete implementation of a ClientTransport that uses the SwiftNIO-based AsyncHTTPClient under the hood.

Maturity Justification

We are proposing this package at the "Sandbox" level of maturity. The project is aiming to release a 1.0 later this year, and we hope to solicit more feedback before we stabilize the API - especially since the spelling of the common abstractions affects all the transport and middleware implementations around the ecosystem.

Minimum Requirements:

  • General
    • Has relevance to Swift on Server specifically: Yes, it fills a gap in the ecosystem.
    • Publicly accessible source managed by an SCM such as github.com or similar: Satisfied: Repository is stored on github.com
    • Prefer to use main as the default branch name, in line with Swift's guidelines: Satisfied
    • Adopt the Swift Code of Conduct: Satisfied
  • Ecosystem
    • Uses SwiftPM: Satisfied
    • Integrated with critical SSWG ecosystem building blocks, e.g., Logging and Metrics APIs, SwiftNIO for IO: It composes well with the existing ecosystem, and was architected for extensibility.
  • Longevity
    • Must be from a team that has more than one public repository (or similar indication of experience): **Satisfied: hosted under Apple organization on GitHub; Active maintainers are @czechboy0, @simonjbeaumont, @glbrntt, and @gjcairo. **
    • SSWG should have access / authorization to graduated repositories in case of emergency: Satisfied (Konrad, Franz, Tomer)
    • Adopt the SSWG Security Best Practices): Satisfied, see SECURITY.md.
  • Testing, CI and Release
    • Have unit tests for Linux: Satisfied
    • CI setup, including testing PRs and the main branch: PRs only for now
    • Follow semantic versioning, with at least one published pre-release (e.g. 0.1.0, 1.0.0-beta.1) or release (e.g. 1.0.0): Satisfied, pre-1.0 semver for now
  • Licensing
    • Apache 2, MIT, or BSD (Apache 2 recommended): Satisfied: Apache 2
  • Conventions and Style

Alternatives considered

The alternative would be for Swift developers to continue to hand-write Swift client and server HTTP ceremony code, while in other language ecosystems they can get the same code generated in seconds. Long term, this would like work as a reason not to adopt Swift, and especially Swift on server.