On generation of API clients from a spec

client_generation.md

Goals

Generate client code from an existing API spec written in Swagger format

• Build type-safe clients for HTTP APIs, so that compatibility is verified at compile time
• Produce client code that is usable as-is and with an express goal of no manual modification, so that generation can be a routine step in a project's build process
• Support multiple languages for clients on suitable platforms. Mainly support languages that have static typing
• Provide an easy-to-understand fluent interface
• Generate both client (accessor) and model (POJO/struct) from the spec

Why not swagger codegen

Swagger codegen is based on templating, which has some limits on the types of inference you can do to build an intuitive or solid client. This article describes some of the issues in even producing a compilable client, and I think that there's need for a tool that's not based on templating alone.

Proposed Language support

• Java (for Android and server-side use)
• Swift
• Maybe JS with type-safety annotations (e.g. JSDoc)

Fluent interface style

I think I'd prefer something like this in Java:

For a GET:

GithubApi github = new GithubApi(httpClient);
Future<GistsGetResponse> gistFuture = github.gists("abc123").doGet();
GistsGetResponse gist = gistFuture.get();

For a PUT/POST:

GistsStarResponse starResponse = github.gists("abc123").star().doPut().get();

or

GistsCommentsResponse commentResponse = github.gists("abc123").comments().doPost(comment).get();

etc...