View
292
Download
1
Category
Tags:
Preview:
Citation preview
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
Recommended