Introducing Bow OpenAPI 0.1.0
by Tomás Ruiz López- •
- February 03, 2020
- •
- swift• functional programming• bow
- |
- 4 minutes to read.
The functional ecosystem around Bow keeps growing with the addition of a new tool: Bow OpenAPI. Bow OpenAPI is a command-line tool that will generate a network client from an OpenAPI or Swagger specification file. Each operation in the specification matches a pure function in Swift that uses Bow Effects to suspend side-effects and helps compose them. The output of the tool is a Swift Package that can be used with Swift Package manager. But there are other benefits too! Keep reading to find out more.
Install it with brew
Bow OpenAPI can easily be installed using brew:
brew tap bow-swift/bow
brew install bow-openapi
It can be used from the command line, or you can integrate it as a build phase in Xcode, making it easier to run.
Always in sync with the specification
OpenAPI/Swagger is a standard format to describe web services. It is commonly used to agree on a contract between providers and consumers on which operations are provided and which data can be exchanged between them for each operation.
As Swift developers, we have worked on several projects where we have been provided such specification, and had to write code to honor it from the client side. This is a repetitive and error prone activity, as there is no guarantee that the code we are writing complies with the contract we have been provided. To make matters worse, if the specification changes, we need to manually update our code to make sure it matches the revised specification.
Bow OpenAPI addresses this by automating the generation of this code. Each endpoint in the OpenAPI specification is transformed into a pure function that uses Bow Effects to suspend its side effects; each data model in the specification results in an immutable value object. If the specification changes, we only need to generate the client again.
Ready for Swift Package Manager
The tool accepts an OpenAPI or Swagger specification file in yaml or json format, and provides a Swift Package as a result that can be consumed directly in your project. You only need to add the dependency and import the generated module to get access to the full suite of operations described in the specification.
Testable out-of-the-box
Besides the module with all your networking functions, the generated Swift Package contains a module that is meant for testing. It contains useful utilities that let you stub responses for the different operations that you want to test. These stubs can be stacked or routed if you are writing integration or end-to-end tests that need to hit multiple endpoints.
As the generated code relies on pure functions, they are intrinsically testable. In fact, you do not need any mocks or special machinery to prepare your code for testing; the configuration object you need to provide in order to perform the network requests will make sure the request does not actually hit the network, but returns the content you have stubbed.
Besides that, custom assertions are provided as part of that module too. They provide expressive power to check that the code you are testing actually provides the results you expect.
Powered by Bow
Besides the generation of your networking client, you get all the benefits of working with Bow Effects, such as error handling, concurrency, or retrial policies. The included combinators in Bow provide a powerful and seamless way of composing side effects.
Conclusion
Bow OpenAPI solves a problem that most Swift teams have to deal with regularly, and it addresses this problem using principled Functional Programming. We are very happy with the outcome of this initial release! The project is open source, so if you give it a try and find any issues, or want a new feature, you can let us know or contribute yourself. We will be glad to welcome you into the Bow ecosystem!
Please check out the following Bow resources. Comments and questions are welcome and encouraged!
Bow is proudly sponsored by 47 Degrees, a Functional Programming consultancy with a focus on the Scala, Kotlin, Swift, and Haskell Programming languages supporting the active development of Bow.