Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
Creative Commons Attr...
Upcoming SlideShare
Loading in …5
×

Writing Comprehensive and Guaranteed Up-to-date REST API Documentation

1,696 views

Published on

SpringOne Platform 2016
Speaker: Andreas Evers; Principal Consultant, Ordina

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.

Published in: Technology
  • Be the first to comment

Writing Comprehensive and Guaranteed Up-to-date REST API Documentation

  1. 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. 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. 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. 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. 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. 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 integratio n
 Icons created by Richard Slater, Ryan Choi, Guillaume Bahri, iconsmind.com from Noun Project
  7. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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

×