Writing documentation for truly RESTful APIs is often done by Swagger or similar tools. However, they provide no support for documenting hypermedia elements, they are URI-centric, leaky and intrusive. Wouldn't it be nice if your documentation could fail your build in case it gets out-of-date with your production code? Wouldn't you want to write your documentation using a format which is designed for writing? Can't there be a tool which documents your code without using the actual implementation? Meet Spring REST Docs. REST Docs allows you to write your documentation as part of your integration tests. In case your documentation doesn't match with your integration test result, your test will fail. This ensures accurate documentation while avoiding the need to put annotations on your production code. It uses the same integration tests to generate snippets, both for request and response bodies, and for hypermedia links. As a writing format it uses asciidoc which is designed for writing.

1. Spring REST Docs
Documenting RESTful APIs using your tests

2. WHOAMI
• Work for Ordina Belgium
• Open source enthusiast
• Spring contributor
• Speaker
• Technical lead & coding architect @ Proximus
• Marathon runner

3. Documentation of
REST APIs

4. Having no documentation
is better than wrong documentation

5. Documentation should be easy to write,
in a format which is designed for writing

6. Frameworks should not be analysing your
implementation to predict documentation

7. Swagger

9. Documentation doesn’t support hypermedia
and is URI centric

10. Data
Links

12. Documentation is intrusive in
the production code

14. Documentation
exposes and relies on
implementation details

16. Framework is heavy

17. A new alternative

18. integration
tests
generated
snippets
manually written
template
generated
HTML

19. Integration test

20. curl-request snippet (generated)
http-request snippet (generated)

21. http-response snippet (generated)

22. links snippet (generated)

23. response-fields snippet (generated)

24. documentation template (manually written)

25. documentation template (manually written)

29. Features

30. Easy to package the
documentation in your
project’s jar file

31. Snippets for
- Hypermedia links
- Request & response payloads
- Request parameters
- Path parameters
- HTTP headers

32. Easy to customise
the request or response
before it is documented

33. Easy to add extra information
to the snippets

34. Easy to ignore parts
of the request or response
during documentation

35. Easy to mark parts
of the request or response
as optional

36. Support for both
JSON and XML

37. Support upcoming for
REST Assured

38. Ideal for brownfield
stubbing

39. Demo

40. Thank you for your attention
@andreasevers
http://projects.spring.io/spring-restdocs/
https://github.com/spring-projects/spring-restdocs