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