Link
Embed
Share
Beginning
This slide
Copy link URL
Copy link URL
Copy iframe embed code
Copy iframe embed code
Copy javascript embed code
Copy javascript embed code
Share
Tweet
Share
Tweet
Slide 1
Slide 1 text
Spring REST Docs Documenting RESTful APIs using your tests
Slide 2
Slide 2 text
WHOAMI • Work for Ordina Belgium • Open source enthusiast • Spring contributor • Speaker • Technical lead & coding architect @ Proximus • Marathon runner
Slide 3
Slide 3 text
Documentation of REST APIs
Slide 4
Slide 4 text
Having no documentation is better than wrong documentation
Slide 5
Slide 5 text
Documentation should be easy to write, in a format which is designed for writing
Slide 6
Slide 6 text
Frameworks should not be analysing your implementation to predict documentation
Slide 7
Slide 7 text
Swagger
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
Documentation doesn’t support hypermedia and is URI centric
Slide 10
Slide 10 text
Data Links
Slide 11
Slide 11 text
No content
Slide 12
Slide 12 text
Documentation is intrusive in the production code
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
Documentation exposes and relies on implementation details
Slide 15
Slide 15 text
No content
Slide 16
Slide 16 text
Framework is heavy
Slide 17
Slide 17 text
A new alternative
Slide 18
Slide 18 text
integration tests generated snippets manually written template generated HTML
Slide 19
Slide 19 text
Integration test
Slide 20
Slide 20 text
curl-request snippet (generated) http-request snippet (generated)
Slide 21
Slide 21 text
http-response snippet (generated)
Slide 22
Slide 22 text
links snippet (generated)
Slide 23
Slide 23 text
response-fields snippet (generated)
Slide 24
Slide 24 text
documentation template (manually written)
Slide 25
Slide 25 text
documentation template (manually written)
Slide 26
Slide 26 text
No content
Slide 27
Slide 27 text
No content
Slide 28
Slide 28 text
No content
Slide 29
Slide 29 text
Features
Slide 30
Slide 30 text
Easy to package the documentation in your project’s jar file
Slide 31
Slide 31 text
Snippets for - Hypermedia links - Request & response payloads - Request parameters - Path parameters - HTTP headers
Slide 32
Slide 32 text
Easy to customise the request or response before it is documented
Slide 33
Slide 33 text
Easy to add extra information to the snippets
Slide 34
Slide 34 text
Easy to ignore parts of the request or response during documentation
Slide 35
Slide 35 text
Easy to mark parts of the request or response as optional
Slide 36
Slide 36 text
Support for both JSON and XML
Slide 37
Slide 37 text
Support upcoming for REST Assured
Slide 38
Slide 38 text
Ideal for brownfield stubbing
Slide 39
Slide 39 text
Demo
Slide 40
Slide 40 text
Thank you for your attention @andreasevers http://projects.spring.io/spring-restdocs/ https://github.com/spring-projects/spring-restdocs