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 

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 

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 

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 illegalArgument() { return new ResponseEntity<>(BAD_REQUEST); } @ApiResponses({ @ApiResponse(code=400, message="…"), @ApiResponse(code=201, message="…")}) return new ResponseEntity<>(BAD_REQUEST); 

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 

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 

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))); 

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) 

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 

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 |=== 

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 } ---- 

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 

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[] 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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