Spring REST Docs - Documenting RESTful APIs using your tests

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.

Transcript

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