[dandlift]

In my team we established a process where our first step is to write down the spec of the API, in swagger format.

The spec is the source of thruth, and is written manually in yaml (that's not that painful). The implementation comes later. Unit tests check that it conforms with the spec. [1] We also have a fake API almost completely autogenerated from the spec that's quite useful for preliminary testing of the clients.

Client code generation wasn't up to my expectations, but I've experimented with applying an handwritten template to a parsed spec and that seems viable.

Swagger as a format might have its quirks, but the tooling is there and having it as the authoritive source of thruth paid off for Us.

[1] https://bitbucket.org/atlassian/swagger-request-validator