1.
Good API
documentation is
executable
Wojtek Erbetowski
@erbetowski

2.
I’m a programmer

3.
Community activist

4.
Head of Engineering at Polidea

5.
Polidea is all about mobile

6.
What is this presentation about?
A little bit about why
A little bit about why not
More about how

7.
Do you document your API?
How many do not document?
How many document on paper/wiki?

8.
How is your API documented?
none/specs
Wiki
Other

9.
Do you do WIKI?
unhappy
happy

10.
Do you do WIKI?
consumers
providers

11.
Simple and easy
Easy to create/change
Easy to modify by nontechnical

12.
Not accurate!
Easily gets out of sync
You never know whether it’s you or them
Not strict
Often inconsistent

13.
How to do it better?

14.
What if ...
… you had plenty of time and money?

15.
Facebook Graph API

16.
DYI solutions

17.
Where’s the value?
Easier to keep up-to-date
Versioning
Non-developers may read and maintain

18.
Not only for big players!
RAML
Swagger
Apiary
I/O Docs
Apigee
...

19.
Most popular tool
Apiary
Swagger
RAML

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

21.
RAML
API first
Readability
Mocking service

22.
An API Is Only As Good As Its
Documentation
Apiary

23.
Comparison
Swagger RAML Apiary
Executable x x x
API Platform x x
Great UI x x
Readability x x
Easily generated x
Scenarios x

24.
Future?

25.
Summary

26.
Your docs can be better!
Get the best of two worlds:
● easy to keep up-to-date
● simple to create/edit

27.
Start with Swagger
simplest in configuration
generates docs from current code

28.
Big decision
Generated vs design first

29.
QUOTES

30.
“I could generate docs from
existing app”
about Swagger and Jersey

31.
“It fails during functional tests
before we see it”
about mocs generated from
documentation

32.
“It’s very hard to return ‘{}’
but how about ‘null’ ? ”
how technology stack affects API design

33.
Q&A

34.
Thank you