- Расскажу и покажу инструменты, которые мы используем для документирования собственного RESTful API.

1. Разработка документации RESTful API:
как убить трёх зайцев
одним выстрелом
Ilya Chesnokov
UK2 Group

2. Documentation is important
● for API users
– frontend developers
– customers using our API
– our techsupport and QA
● for API developers
– code review
– further use, development and refactoring of API
– documentation (design)-driven development

3. Perl - POD
● “Native” documentation format for Perl
● Easy to learn
● Simple to use
● Easily parseable
● Extensible (if you have fantasy)

4. How to read docs?
● perldoc
● unparsed source
● convert to HTML and read in a browser

5. How to read docs?
● perldoc
– programmers only!
● unparsed source
– programmers only!
● convert to HTML and read in a browser
– everyone

6. We need a converter!

7. What is documented?
● General description
● API routes and methods
● Input parameters
● Output data
– Possible errors

8. What is documented?
● General description =head1, =head2
● API routes and methods =head3
● Input parameters =head4, =item
● Output data =head4, =item
– Possible errors

10. =head3 POST /login
Loging using your credentials.
=head4 Input
=over
=item username
Username to login with.
=item password
Password to login with.
=back
=head4 Output
...
The POD

15. Tweaks: common output

17. =head3 ANY /domain/:domain
=head4 Output
...common output...
=head3 GET /domain/:domain
=for docviewer output-from ANY /domain/:domain
=head4 Output
...specific output ...
Common output

18. Results
● DDD FTW!
– documentation is always up to date
– good programming practice
● Testing (by hand) becomes even more easy
● No need to write an admin panel
– people use API console instead

19. Repository
https://github.com/LoonyPandora/Pod
-HTML5-Browser

20. Thank you!
Ilya Chesnokov <chesnokov.ilya@gmail.com>