The document discusses API documentation and provides tips for improving it. It recommends taking a doc-driven development approach where documentation explains the business logic and declares how the API will evolve. The documentation should not just list endpoints but provide enough detail to serve as the contract with customers for how the API works.

1. API Documentation
Gabriele Mittica - @gabrielemittica

2. APICONF 2017- Gabriele Mittica
Documentation can be boring!

3. APICONF 2017- Gabriele Mittica
Design
Define
Doc
Code
Test
Manage

4. The goal
▪ Set interfaces and nomenclatures
▪ Define input and output
▪ Define error codes and responses
APICONF 2017 – Gabriele Mittica

5. The problem
▪ It’s a long job
▪ List endpoints is not enough
▪ I need to put business logic in to documentation
APICONF 2017 – Gabriele Mittica

6. How to
▪ Doc-driven and test-driven development
▪ Explain business logic
▪ Declare versioning and growth of APIs
▪ Don’t create doc by layout but by logic
APICONF 2017 – Gabriele Mittica

7. APICONF 2017- Gabriele Mittica
Doc
Design
Define
CodeTest
Manage

8. The doc is the only
contract with the
customer
Thanks for Listening
APICONF 2017- Gabriele Mittica