Good API documentation is

executableWojtek Erbetowski

@erbetowski

I’m a programmer

Community activist

Head of Engineering at Polidea

Polidea is all about mobile

What is this presentation about?

A little bit about why

A little bit about why not

More about how

Do you document your API?

How many do not document?

How many document on paper/wiki?

none/specs

WikiOther

How is your API documented?

Do you do WIKI?

unhappy

happy

Do you do WIKI?

consumers

providers

Simple and easy

Easy to create/change

Easy to modify by nontechnical

Not accurate!

Easily gets out of sync

You never know whether it’s you or them

Not strict

Often inconsistent

How to do it better?

What if ...

… you had plenty of time and money?

Facebook Graph API

DYI solutions

Where’s the value?

Easier to keep up-to-date

Versioning

Non-developers may read and maintain

Not only for big players!

RAML

Swagger

Apiary

I/O Docs

Apigee

...

Most popular tool

Apiary

Swagger

RAML

“Give a man an API, and he APIs for a day. Teach a man to API, and he APIs for a lifetime.”

Swagger

RAML

API first

Readability

Mocking service

An API Is Only As Good As Its Documentation

Apiary

Comparison

Swagger RAML Apiary

Executable x x x

API Platform x x

Great UI x x

Readability x x

Easily generated x

Scenarios x

Future?

Summary

Your docs can be better!

Get the best of two worlds:

● easy to keep up-to-date

● simple to create/edit

Start with Swagger

simplest in configuration

generates docs from current code

Big decision

Generated vs design first

QUOTES

“I could generate docs from existing app”

about Swagger and Jersey

“It fails during functional tests before we see it”

about mocs generated from documentation

“It’s very hard to return ‘{}’but how about ‘null’ ? ”

how technology stack affects API design

Q&A

Thank you