Generate and test RESTful APIs in Swift

Don’t spend hours writing code for a client API to interact with a server. Writing such code is tedious and repetitive if you support various clients in different programming languages.

Don’t wait to start developing against a service that may not yet exist or for which you are waiting to get access.

You can create a fully functional client API and test it with a mocked backend literally in minutes with the help of some excellent open-source tools!

Swagger and Mockoon

Based on a real-life example, using the existing IP geolocation API, I will explain and show you how to

1. Get a RESTful API definition of the backend
2. Mock the backend
3. Generate a Swift client library
4. Use the Swift client library in an application

Get a RESTful API definition of the backend

RESTful APIs can be described in a standard, language-agnostic way. This allows both humans and computers to discover and understand the service’s capabilities without access to source code, documentation, or through network traffic inspection. This standard is called OpenAPI specification, previously known as Swagger. Today, the term Swagger is still around but describes a set of tools for implementing the OpenAPI specification, e.g.

• Swagger Editor: lets you edit OpenAPI specifications in YAML inside your browser and preview documentation in real-time.
• Swagger Codegen: Allows generation of API client libraries (SDK generation), server stubs, and documentation based on an OpenAPI Spec.

Browse through a repository of existing RESTful API definitions. You can also contribute to this “Wikipedia for Web APIs” as the folks of API gurus published it on GitHub.

OpenAPI directory of apigurus.com

As an example, I will take this particular specification of an IP geolocation API. The folks from AbstractAPI allow developers to retrieve the region, country, and city behind any IP worldwide. No Swift client library exists yet.

IP Geolocation API

Let’s open the specification in the browser through Swagger Editor.

Swagger Editor

A single HTTP GET request for the v1 endpoint allows us to retrieve a bunch of geolocation information based on an IP address.

I haven’t signed up, so I don’t have access to the backend.

Mock the backend

Mockoon is a great application to run mock APIs locally easily. No remote deployment is needed, no hassle with account management. And it is open source with multi-platform support:

You can download it from mockoon.com. Mockoon is also available through Homebrew brew install --cask mockoon.

Once installed, you can import an OpenAPI spec.

Import specification into Mockoon

Per default, the mocked service is using Mokoon’s templating system to create dynamic responses.

Running a mock server with Mockoon

So you can start your server and test it straight away. For simple HTTP requests, you can use curl. For more complex HTTP requests I recommend an app like Postman or Paw

Testing mock server with curl

In this particular example, I did a minor change manually to improve the mocked response. I leveraged Faker.js with Handlebars to mock address-related information, e.g. "city": "{{faker 'address.city'}}"

Generate a Swift client library

There are multiple options to generate a client library for a backend service conveniently.

• Swagger Codegen: Model and API generation from Swagger 2.0 or OpenAPI 3.0 spec. Dependency to popular networking library Alamofire
• SwagGen: command-line tool that generates code from a OpenAPI/Swagger 3.0 spec. It is an alternative to the official Swagger-Codegen Java code generator and “adds some improvements such as speed, configurability, simplicity, extensibility, and an improved templating language”.

I’ll use usw Swagger Codegen as the generation is possible through the Swagger Editor in the browser. No tools are needed to install on my local machine :)

Generate Swift code straight out of the browser

Even if you are not a Swift developer, there is a pretty good chance that Swagger Codegen can speed up your development process. Because the generation of API client libraries and server stubs are possible in multiple languages, e.g. C#, C++, Go, Java, Python, and many more.

But I understand that Swagger Codegen might not suit your needs due to the dependency on Alamofire. In fact, when writing this article, Swagger Codegen relies on Alamofire 4.x, and using the Alamofire 5.x (released February 2020) would require you to fix the generated code to make it compatible with Alamofire 5.x.

If you don’t have an Open API specification and simply a JSON representing the model of the HTTP response, then use quicktype. Try it in the browser or as a command-line tool, and it will generate strongly typed models and serializers in Swift for you. Also, here multiple target languages are supported.

Use the Swift client library in an application

The following steps are needed to use such a generated client library by Swagger Codegen:

• Add Alamofire 4.x to your Xcode project, e.g. through Swift Package Manager
• Unzip, copy and add the Swagger Client folder to your Xcode project
• Use the desired APIs and their models located in the APIs and Models folder

For the IP Geolocation API the generated API code looks as follow

API model to initiate a URL request to v1 endpoint

And here is the response model:

Response model for v1 endpoint

To connect to the mock server, powered by Mockoon, you have to replace the basePath in SwaggerClientAPI.

SwaggerClientAPI with basePath

And there is the final example of how to invoke the client API to trigger an HTTP request to the mocked backend and receive a response.

How to send a URL request to mock server

All source code, included in a SwiftUI application, can be found on GitHub.

Originally published at https://blog.eidinger.info.