Writing Comprehensive and Guaranteed Up-to-date REST API Documentation - SpringOne Platform 2016

RESTful APIs are eating the world, yet all too often the documentation can cause indigestion for the APIs' developers and their users. Developers have to deal with annotation overload, repetition, and an unpleasant writing environment. Users are then left with documentation that's inaccurate and difficult to use. It doesn't have to be this way.

This talk will introduce Spring REST Docs and its test-driven approach to RESTful API documentation. We'll look at how it combines the power of Asciidoctor and your integration tests to produce documentation that's accurate and easy-to-read, while keeping your code DRY and free from annotation overload. We'll also look at some of the features that are new in Spring REST Docs 1.1, including support for REST Assured and Markdown.

Transcript

1. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Writing Comprehensive and Guaranteed Up-to-date REST API Documentation By Andreas Evers @andreasevers
2. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Keep the documentation accurate 2
3. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Document in the right place 3 Controller Jackson Response Entity HTTP response POJO
4. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Keep it DRY 4 @ResponseStatus(CREATED) HttpHeaders create( @RequestBody UserInput userInput) { … } @ExceptionHandler( IllegalArgumentException.class) ResponseEntity<Void> illegalArgument() { return new ResponseEntity<>(BAD_REQUEST); } @ApiResponses({ @ApiResponse(code=400, message="…"), @ApiResponse(code=201, message="…")}) return new ResponseEntity<>(BAD_REQUEST);
5. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Write docs in markdown or asciidoc 5
6. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ 6 generated snippets manually written template generated HTML integration
 tests Icons created by Richard Slater, Ryan Choi, Guillaume Bahri, iconsmind.com from Noun Project
7. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Integration test 7 this.mockMvc.perform(get("/cars/{carId}","1")) .andExpect(status().isOk()) .andDo(document("cars", pathParameters( parameterWithName("carId") .description("Id of the car")), responseFields( fieldWithPath("brand") .description("Brand of the car")) .and(this.otherFields)));
8. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Request snippets 8 [source,bash] ---- $ curl 'http://localhost:8080/cars/1' -i ---- [source,bash] ---- $ http GET 'http://localhost:8080/cars/1' ---- Curl Request HTTPie Request (new in 1.1)
9. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Request snippets 9 [source,http,options="nowrap"] ---- GET /cars/1 HTTP/1.1 Host: localhost ---- HTTP Request
10. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Request path parameters snippet 10 ./cars/{carId} |=== |Parameter|Description |carId |Id of the car |===
11. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Response snippet 11 [source,http,options=“nowrap"] ---- HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: 150 { "brand" : "BMW", "constructionYear" : 2010 } ----
12. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ All snippets 12 Request - Curl request - HTTP request - HTTPie request Request fields Request path parameters Request parameters Request headers Request parts (new in 1.1) Response Response fields Hypermedia links Response headers Response fields
13. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Documentation template 13 [[resources-car-get]] === Retrieving a car For retrieving a car, the following path parameter has to be used to indicate which car to retrieve: include::{snippets}/car-get/path-parameters.adoc[] For example, a curl request for the first car in the repository looks like this: include::{snippets}/car-get/curl-request.adoc[]
14. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Documentation HTML 14
15. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Demo 15
16. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Easy to package the documentation
 in your project’s jar file 16
17. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Easy to customize the request or response
 before it is documented 17
18. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Support for reusing common documentation 18
19. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Easy to add extra information to the snippets 19
20. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Easy to document constraints of fields 20
21. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Easy to ignore parts of the request or response
 during documentation 21
22. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Possibility to switch off failing
 on inaccurate documentation 22
23. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Easy to mark parts of the request or response
 as optional 23
24. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Support for both JSON and XML 24
25. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Support for REST Assured 25
26. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Ideal for brownfield stubbing 26
27. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/ Thank you for your attention @andreasevers http://projects.spring.io/spring-restdocs/ https://github.com/spring-projects/spring-restdocs @springcentral spring.io/blog @pivotal pivotal.io/blog @pivotalcf http://engineering.pivotal.io