Spring REST DocsDocumenting RESTful APIs using your tests

WHOAMI

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

Documentation of REST APIs

Having no documentation is better than wrong documentation

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

Frameworks should not be analysing your implementation to predict documentation

Swagger

Documentation doesn’t support hypermedia and is URI centric

Data

Links

Documentation is intrusive in the production code

Documentation exposes and relies on

implementation details

Framework is heavy

A new alternative

integration tests

generated snippets

manually written template

generated HTML

Integration test

curl-request snippet (generated)

http-request snippet (generated)

http-response snippet (generated)

links snippet (generated)

response-fields snippet (generated)

documentation template (manually written)

documentation template (manually written)

Features

Easy to package the documentation in your

project’s jar file

Snippets for

- Hypermedia links - Request & response payloads - Request parameters - Path parameters - HTTP headers

Easy to customisethe request or responsebefore it is documented

Easy to add extra information to the snippets

Easy to ignore partsof the request or response

during documentation

Easy to mark parts of the request or response

as optional

Support for bothJSON and XML

Support upcoming forREST Assured

Ideal for brownfieldstubbing

Demo

Thank you for your attention

@andreasevers

http://projects.spring.io/spring-restdocs/

https://github.com/spring-projects/spring-restdocs