How do you keep your REST API documented? Online description? Or maybe a spreadsheet/doc? Think about how does your consumer discover it. Poor one is pasting URLs to curl or POSTman, right? And he’s mad as hell, as documentation is out of sync with code as soon as it’s written. Not to mention submitting bugs looks like an email ping-pong. It’s not 2010 any more, you know? Let’s jump into cool tools that will improve your consumers’ life and save you some time.

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
...

20. Most popular tool
Apiary
Swagger
RAML

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

22. RAML
API first
Readability
Mocking service

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

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

25. Future?

27. Summary

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

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

30. Big decision
Generated vs design first

31. QUOTES

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

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

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

35. Q&A

36. Thank you