A task coming across quite often is specifying a REST API for the server-side component of an App. There are many approaches to this from doing everything by hand up to using services like Contentful that even release one from the burden of having to write any code.

Time has taught me it is better to own the server instead of having to rely on somebody else. Services change or might go away completely (Parse, anyone?). Even if having to take care of maintaining the code base has an impact on the effort necessary to keep the system running it usually pays off.

Before starting to write any code for the API server it is necessary to write done its specification to avoid confusion and uncertainty. This can be a quite tedious task, but it is exactly where Swagger and it tools can help.

Swagger advertises itself as a “Framework for APIs” and that’s a perfect summary. It consists of a definition how APIs are meant to be described, an editor with syntax checking to help writing the definition, and tools to automatically create boiler-plate code for the server as well as client SDKs. The later two tools are capable of creating code for a wide range of programming languages. A very convenient option, but not necessary if you prefer to write it yourself. For example, in my case the way the code generator for the Swift SDK created the data models would have been to inflexible. It also used object classes instead of structs as I would have preferred it. But your mileage may vary.

I am currently using Swagger and its editor to create the definition and write all code myself. But alone that is such a great help since API docs can be created from this to help all members of the project to have a reliable definition.