A few weeks ago, I began working on a new project. Instead of working together with a team of web developers and designing all APIs from scratch, the server API was already available as we had to connect to the existing service of our client. A brief look at the API documentation revealed, that I have no desire in writing all the models and calls from scratch. As the documentation also had an interactive version supported by Swagger, including a swagger.json file that is a nice representation of all the models and APIs and the corresponding data that you'll have to send and receive, I took a dive into tools that could generate some kind of an SDK for the project.

I aimed for the following requirements:

• generate models and API definitions from swagger.json
• customizable templates
• optional: multiple templates to support multiple platforms

I was expecting that I have to write my own tool. If I had to, I would probably go with Node.js, TypeScript, and the @apidevtools/swagger-parser package.

But after asking on Twitter I got pointed at the Swagger Codegen project. It is Java-based and I had no intention to install Java on my system. At least you can execute the CLI via Docker and the official container. You only have to write and compile Java code if you want to create a complete custom generator. But as they already provide a lot of templates, including a swift5 template, I gave that one a shot.

Swagger Codegen

The models are fine as they are. Structs conforming to Codable with optionally generated CodingKeys, all properties available, and even an initializer for all the properties. Everything public and ready to be used as a dedicated package. Well... almost.

The API files are what I was most concerned about. These will require customization from my side and I knew this before I started searching for solutions. But I wanted to see what the default output looks like.

The swift5 template at its core requires Alamofire and can be extended to support PromiseKit and/or RxSwift. I don't need any of these dependencies at the moment and the generated code comes with a bit of boilerplate code that I don't need as well. Luckily there is an option to only generate the API and model files.

-Dmodels -Dapis

Customizing the template is as easy as creating my own template directory and naming the templates the same way, the generator (click here for the swift5 generator files) uses them. Swagger Codegen uses mustache templating. The V3 Variant uses the Java implementation of Handlebars which is compatible with existing mustache templates. Documentation on the official sites is fine, but if you don't want to touch the Java code of the generators like me, you are stuck with the features the used libraries provide. And I got stuck pretty early: There is no option to lowercase or uppercase a value. At least I haven't found one without manipulating the generators java files and registering the StringHelpers that are available in the Handlebars Java implementation but have to be enabled manually.

This at the moment keeps me from using the Swagger Codegen project, but luckily there is an alternative by OpenAPI called the OpenAPI Generator. As Swagger makes use of the OpenAPI specifications this could work.

Next try: OpenAPI Generator

It uses Java as well and a Docker container is available, too. And most important: A full-fledged documentation website including a section about modifying and writing templates and even the options of the swift5-generator.

The OpenAPI Generator uses basically the same logic as the Swagger Codegen project, but templates have a few more extensions to use in the mustache templates. These extended functions are called lambdas. These are neatly documented in the templating documentation I linked above.

As lambdas for uppercase and lowercase are available, I began customizing the output. I only had to create my own version of the api.mustache file inside my own template folder. As a reference, I used the original file to get to know about all the properties and the templating syntax.

You can use the same command line parameter as for Swagger Codegen above to only generate API and model files. I ended up adding some of my own support files and customized the output by using a  config.yml and told the CLI to use it. Of course, there is documentation.

-c <path to config.yml>

I disabled all the other files and ended up with a config like this:

templateDir: /local/templates/swift-customized
projectName: MyAPI
useBacktickEscapes: true
useJsonEncodable: false 
files:
  StringRepresentation.swift:
    folder: MyAPI/Classes/OpenAPIs
  JSONEndpoint.swift:
    folder: MyAPI/Classes/OpenAPIs
  XcodeGen.mustache: 
    folder: unused
  APIHelper.mustache:
    folder: unused
  APIs.mustache:
    folder: unused
  CodableHelper.mustache:
    folder: unused
  Cartfile.mustache:
    folder: unused
  Configuration.mustache:
    folder: unused
  Extensions.mustache:
    folder: unused
  JSONDataEncoding.mustache:
    folder: unused
  JSONEncodingHelper.mustache:
    folder: unused
  Models.mustache:
    folder: unused
  OpenISO8601DateFormatter.mustache:
    folder: unused
  Podspec.mustache:
    folder: unused
  README.mustache:
    folder: unused
  SynchronizedDictionary.mustache:
    folder: unused
  URLSessionImplementations.mustache:
    folder: unused 
  gitignore.mustache:
    folder: unused 
  git_push.sh.mustache:
    folder: unused 
  api_doc.mustache:
    folder: unused 

What I did was move everything that I don't need into a folder called unused and added my custom files to the target location at the top. As you can see, I will not use the Podspec or Cartfile templates, as we only use Swift Package Manager at this stage.

As I created a small shell script to run the generator, I added a few lines to delete the unused-folder after generating everything and also used SwiftFormat at the end, because writing the templates with a good output formatting was way harder than I thought.

It is only as good as the documentation

Over the time of regenerating and using the generated code in the project, my colleague and I have noticed that sometimes the attributes of the models got moved around which resulted in a different parameter order for the initializer of that model. This of course ended up messing with the code where we created our own instances as input to an API.

This happened because the swagger generator on the server side messed it up on a few models over time. To fix that, I added a python script to sort all the keys of the swagger.json before passing it to the OpenAPI Generator.

Some data types have been messed up like a Date response type was documented as Int, but that could be fixed after editing the documentation header on the server side.

Creating a script

As I have mentioned above, I did a bunch of extra stuff to get an output I was satisfied with.

1. Download the swagger.json from the server
2. Sort the JSON
3. Run the generator via docker
4. cleanup output
5. format output

Your mileage may vary depending on your server-side documentation generator and the output SDK language you use.

My shell script for the Swift output looked like this at the end:

LANGUAGE="swift5"
SOURCE="https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore-expanded.json"
SOURCE_DUMP_FILE="swagger.json"

# 1. download swagger.json
curl $SOURCE > $SOURCE_DUMP_FILE

# 2. sort swagger json to sort model properties
python3 jsonSort.py $SOURCE_DUMP_FILE

# 3. generate SDK
docker run 
  --rm \
  -v "${PWD}:/local" \ # link current folder to /local in the container
  openapitools/openapi-generator-cli generate \
  -i /local/$SOURCE_DUMP_FILE \
  -g $LANGUAGE \
  -o "/local/out/$LANGUAGE" \
  -c /local/config-iOS.yaml

# 4. Cleanup unused files
rm -r "${PWD}/out/$LANGUAGE/unused"
rm -r "${PWD}/out/$LANGUAGE/docs"
rm -r "${PWD}/out/$LANGUAGE/.openapi-generator"
rm "${PWD}/out/$LANGUAGE/.openapi-generator-ignore"
rm "${PWD}/out/$LANGUAGE/.swiftformat"

# 5. Swift Format
if which swiftformat >/dev/null; then
  swiftformat "${PWD}/out/$LANGUAGE/"
else
  echo "warning: swiftformat not installed."
  echo "Install via"
  echo "\tbrew install swiftformat"
fi

Feel free to modify it to your needs.

Summary

It was a bit of work to learn the templating syntax and find out about the parameters and properties to use. But looking at the original templates helped a lot.

The project where I used this generator had over 30 Endpoints and over 200(!) models. Writing all these by hand would've been madness. And they changed in some spots over time. Some of the model files are not even used, because abstract model definitions are treated as a regular model. For example, we have an abstract DatabaseObject model, that has an id, createdAt and updatedAt field and it is the base for most of the models. This, in my case, will generate a corresponding Swift model, but the other models are not a subclass of this model. They still have the properties on their own, but in the code, we will never refer to the DatabaseObject model.

In some places, it would've been cool to use the abstract definitions as a protocol, but I didn't find a neat way to realize it. But you can always create a few extensions by hand if you need them. We tried never to hack the generated files and keep the output as clean as possible. Any extension happened separately from the API Package.

All the time I used to modify everything to our needs was nothing compared to the time this saved us now and will in the future as this reconfiguration for our architecture can be reused very easily for any future project.

CodingKeys are created to map data between your model and the data. These are mostly created as an enum to easily map the data in a custom decoding or encoding logic. If you don't declare the keys yourself, the compiler will do this automatically for you. But as we want to map data differently we will to this on our own now.

An object that defines the coding keys has to conform to the protocol CodingKey (no s). This has to have two initializers: One init?(intValue: Int) and `init?(stringValue: String)` with corresponding properties var intValue: Int? { get }? and var stringValue: String { get } (Apple Documentation). As you can see, stringValue is not optional. This is because the keys of a dictionary use strings in most cases or can be at least converted to a string. Arrays are automatically handled by iterating the data and don't require a coding key for each index.

The easiest way to conform to this protocol is to use an enum with a defined RawValue and this is what I'll use in my example.

This will be our input JSON for now:

{
    "id": "5A30CB22-76C8-4A2D-A86E-5AB181DD5838",
    "username": "CBeloch",
    "age": 30
}

Let's take our example from above and map id of the incoming data to our property called identifier.

struct User {
    let identifier: String
    let username: String
    let age: Int
}

// MARK: Codable

extension User: Codable {
    private enum CodingKeys: String, CodingKey {
        case identifier = "id"
        case username
        case age
    }
}

And thats it! The enum has a String as RawValue type and we set the value of the identifier case to `"id"`. The raw values for username and age are automatically generated, based on their name. The important part is, that the names for the keys have to match the property names and that you add a key for all of your properties.

You can restrict access to the CodingKeys by setting them to private so you can't access the keys from the outside by using User.CodingKeys.

In the next chapter I'll show you how to write your own decoder logic for your model which will be an initializer. In that chapter, naming of the CodingKeys enum and naming of the keys will not matter anymore.

Most of our (De-) Serializing work is done by Codables themself. All keys of the data structure are mapped directly to the property names of your model. Without any modification to the naming. But in most cases you want to optimize the data in a way that works better for you.

At first you should check out what options your Coder gives you that could already fix a lot of your issues with the naming of the API and your model properties.

keyDecodingStrategy

The JSONDecoder for example has a keyDecodingStrategy property which can be set to .useDefaultKeys (default) or .convertFromSnakeCase. This fixes the  issues that you get a snake_case (words separated by underscores) property from an API, but you want your model properties to be camelCase (words separated by uppercasing the first letter of the new word). This is also available on the JSONEncoder with equivalent naming of keyEncodingStrategy and .convertToSnakeCase.

Data and Date conversion

And the JSON Coders have strategy options for Data and Date conversion. The properties for this are named dataEncodingStrategy and dateEncodingStrategy for the

Data is converted from and to Base64 by default and Date will be encoded by it's own encoding/decoding logic by default (.deferredToDate). But the strategy can be changed to .iso8601 which creates/parses an ISO 8601 compatible string, .formatted(DateFormatter) which takes a custom DateFormatter or if you are more into UNIX timestamps: .secondsSince1970 and .millisecondsSince1970.

All of these strategy options also have a .custom option. More on that in a later chapter when we get into ValueContainer. (A Link will follow as soon as the article is online)

A short annotation if you are using a PHP based backend for your app:‌‌‌‌PHP does have an option to encode a DateTime object to ISO 8601 and it works fine on the decoding side of your app. But if you want to send a Date whereas you have to encode it to an ISO 8601 string, this doesn't work in most cases. That's because PHP isn't conforming to the standard and uses a default format of  "Y-m-d\TH:i:sO" (Source) - The O indicates a timezone like +0100, but Z is valid for UTC timezone by ISO 8601 definition, but PHP throws an error if it gets such a date string for parsing.‌‌‌‌Use a .formatted(DateFormatter) strategy and use "yyyy-MM-dd'T'HH:mm:ssxxxx" as your dateFormat on the app side.

This is it for the Coder options. At least for the JSON Coder provided by the Swift Standard Library. The PropertyListEncoder only has an option for the output format. If you want the encoded data to be binary, xml or openStep formatted. The corresponding decoder has no options at all.

Additional note: Both the JSON and PropertyList Encoder and Decoder are available on Linux as well.

There are 3rd party Encoder and Decoder out there, just check their documentation on how to modify their logic. Maybe this options will already help you a lot.

References

• JSON
  • JSONDecoder
  • JSONEncoder
• Property List
  • PropertyListDecoder
  • PropertyListEncoder
• 3rd Party
  • MsgPack
  • XML

It has been a long time we used stuff like NSJSONSerialization or NSPropertyListSerialization and dropped the NS prefix in favor of Swift. It helped converting data from or to JSON / Property List. Creating an instance of your model classes or serialize them to one of the formats would require writing a lot of additional code to convert the values to the correct data types.

Well, the time of these has come to an end and since Swift 4 we got a hand full of new protocols that allow the compiler to generate all the necessary code in the background. But we will still be able to customize the behaviours. More on that in a later chapter. Let us begin with the basics.

The Protocols

There are only two (or three) protocols that you really have to care about: Decodable and Encodable. And Codable, but that is only a type alias for Decodable & Encodable so it is just a simpler annotation when you want a model do be de- and encodable.

Decodable

This is the protocol when you want to decode data to your model. When you work with external Web-APIs which are JSON, you will most likely use Decodable to work with you model within your app.

Encodable

For the serialization part, meaning you want to store your model data in a file or send it out to an API, Encodable is you protocol of choice.

Codable conformant types

Most of the data types you get from the Swift Standard Library are conformant to Decodable and Encodable. You can find a complete list in the documentation provided by Apple. I linked the conformant types for Decodable, but all of these types also work for Encodable.

As you can see, event objects like CGPoint and CGSize are listed and completly conform to the Codable protocol. But they are represented as an array of float values. CGRect is represented as an array of arrays with float values. This may not be the ideal way of  representing the data, but it could be enough if you just want to store data in a local file instead of accessing a self-explaining API.

Date and Data are special snowflakes in the Codable space. At least if you want to use a JSONDe-/Encoder. These Coders special settings to modify the strategy on how a Date will be (de-)serialized. ISO-8601 formatted? UNIX timstamp? No problem at all. You can even add your own strategy. More on this in a later chapter.

Example

For convenience I will mostly use JSON in my examples because it is more readable than a full fledged property list.

Lets take this product list as a short example to introduce you to Codables:

let jsonString = """
[{
  "title": "Awesome new Book",
  "price": 12.99,
  "currency": "EUR"
},{
  "title": "Fantastic Movie",
  "price": 9,
  "currency": "USD"
}]
"""

Our goal is to parse this data that can be extended in the future and work with a Product model within my app.

Model

struct Product: Codable {
    let title: String
    let price: Double
}

Let us leave out the currency property at this step. We get back to it in a minute.

Decode JSON

To decode our jsonString, we have to convert it to a Data object

let jsonData: Data = Data(jsonString.utf8)

I'm doing it this way, because jsonString.data(using: .utf8) would result in an optional Data (Data?) type and I don't want to unwrap it and force unwraps are my most hated lines of code.

As we use JSON in our example, we need a JSONDecoder that is happily provided by Swift. Most decoders have a simple func decode(_:from:) function.

let decoder = JSONDecoder()

do {
    let deserializedData = try decoder.decode(Array<Product>.self, from: jsonData)
} catch {
    print("Decoding Error", error)
}

deserializedData is now from type Array<Product> or [Product] if you like the later one more.

If the decoding fails, you'll get an error explaining what went wrong and where. Like a key that is missing or was the wrong data type.

Recursive De-/Encoding

As I mentioned above, I left the currency value out of the model. Thats because I would like to implement this as an enum. You can add any other type to your model as they are recursively conformant to the same Codable protocols. This means that as our Product model is Codable, our enum has to be Codable as well.

Enums

For an enum to be En- and/or Decodable, it has to have a raw value if we don't want to write the logics for (de)serializing the object. We will come to that in a later, more advanced guide.

Lets add our currency enum:

struct Product: Codable {
    let title: String
    let price: Double
    let currency: Currency // added the property
}

enum Currency: String, Codable {
    case usDollar = "USD"
    case euro = "EUR"
}

This is it. We now have a currency property with an enum. One thing to notice: Any other value (like "GBP") will cause the deserialization to fail! And the most sad part is that it will also fail when you set currency to be an optional value.

Encode JSON

Encoding works just like decoding. Just instead of a JSONDecoder we use a JSONEncoder:

let encoder = JSONEncoder()
do {
    // deserializedData contains our Product array
    let serializedProductsData: Data = try encoder.encode(deserializedData)
    
    // Convert Data to String
    let serializedProductsString: String = String(data: serializedProductsData, encoding: .utf8)
} catch {
    print("Encoding Error", error)
}

At this stage we could also convert the data to a plist by using a PropertyListEncoder.

Please note, that you'll lose all properties on the encoding side that hadn't been parsed on the decoding side. If you use the example without the currency property, the encoding will drop that, too.

Wrap it up

I hope you got a little insight in how to work with Codables without using any Frameworks or fancy code. We will get into it and dive a little deeper in the next guides around this topic and how to handle stuff like the enum issue above and how to work with annoying APIs that you can streamline a little bit with Codables.

I will explain how to write custom (de)serialization for your models and how to solve some issues that can occur.

When you develop native in Apples environment, you stumble over CocoaPods to implement 3rd party libraries in your apps. It adds dependencies that can be installed separately and don't have to be stored in your respositories.

I used it for a few years now, but it gets worse every week so I'm leaving and switching to Carthage.

So what is the problem with CocoaPods?

It's centralized

All Libraries are submitted to a central git repository hosted on GitHub or you create your own specs repository and modify your Podfile in you project to use that one.

Complicated Syntax

The syntax for adding your own private Pods to the dependencies is a little bit messy:

pod 'MySecretLib', :git => 'git@github.com:SomeKindOfCode/ThatSecretLib.git'

And can get worse when you specify a specific branch, commit or version:

pod 'MySecretLib', :git => 'git@github.com:SomeKindOfCode/ThatSecretLib.git', :branch => 'develop'  
pod 'MyOtherLib', :git => 'git@github.com:SomeKindOfCode/MyOtherLib.git', :tag => '1.3.5'

Using a version operator like ~> 1.0 is not possible here.

Patchwork without (much) control

This is one of the main issues for me.

When you run pod install, CocoaPods will generate a Pods.xcodeproj for you and if it doesn't exist, creates a Xcode workspace file for you. The last one isn't an issue, but the first is.

When you develop a framework for CocoaPods, you can throw everything into a folder, add a .podspec to your reposoitory and submit it. Everything else is controlled via a 3rd party. There is no requirement to create a custom Xcode project.

Due to these steps which change a few things with each CocoaPods Version I recently ran into a large amount of signing issues.
It cost me a day of work to get my app fixed to be submitted to the App Store. The only fix was another project manipulation I had to add to my Podfile.

post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['EXPANDED_CODE_SIGN_IDENTITY'] = ""
            config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
            config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
        end
    end
end

This disabled the codesigning on the frameworks. I hate this step and this has to be done for each app you develop.
I got sick of it. Every new version broke something different so I moved over to Carthage which gives you much more control, is decentralized and builds real frameworks!

This automatic generation is also the problem why you can't migrate all Pods to Carthage. Most will work, but every now and then I've stumbled over projects that were created in the most simple way. If you want to develop your own Framework, consider using something like SwiftPlate by John Sundell.

Updated March 1st 2019