Spring REST Docs — Documenting RESTful APIs

Slides of the talk I held at OOP 2016.

@springcentral

Transcript

1. Spring REST Docs DOCUMENTING RESTFUL APIS / @OLIVERGIERKE / @ANKINSON
3. Hypermedia Documenting
 APIs?
4. Let’s use
 code
 generation!
5. Meet:
 Swagger…
6. It’s URI centric
7. Baking URIs into clients breaks independent deployability
8. It doesn’t support hypermedia https://github.com/swagger-api/swagger-core/issues/97
9. Always playing catch up – ResponseEntity https://github.com/springfox/springfox/issues/532
10. The writing experience is unpleasant @ApiOperation(value = "Create a new user", notes = "The name " + "of the user must be at least four characters in length.") @ApiResponses({ @ApiResponse(code = 400, message = "Bad request"), @ApiResponse(code = 201, message = "User created")}) @ResponseStatus(HttpStatus.CREATED) @RequestMapping(method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE) public HttpHeaders create(@RequestBody UserInput userInput) { … }
11. It isn’t dry @ApiResponses({ @ApiResponse(code=400, message="Bad request"), @ApiResponse(code=201, message="User created")}) @ResponseStatus(HttpStatus.CREATED) public HttpHeaders create(@RequestBody UserInput userInput) { … } @ExceptionHandler(IllegalArgumentException.class) private ResponseEntity<Void> handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.BAD_REQUEST); }
12. @ApiResponses({ @ApiResponse(code=400, message="Bad request"), @ApiResponse(code=201, message="User created")}) @ResponseStatus(HttpStatus.CREATED) public HttpHeaders create(@RequestBody UserInput userInput) { … } @ExceptionHandler(IllegalArgumentException.class) private ResponseEntity<Void> handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.BAD_REQUEST); } It isn’t dry
13. @ApiResponses({ @ApiResponse(code=400, message="Bad request"), @ApiResponse(code=201, message="User created")}) @ResponseStatus(HttpStatus.CREATED) public HttpHeaders create(@RequestBody UserInput userInput) { … } @ExceptionHandler(IllegalArgumentException.class) private ResponseEntity<Void> handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.BAD_REQUEST); } It isn’t dry
14. @ApiResponses({ @ApiResponse(code=400, message="Bad request"), @ApiResponse(code=201, message="User created")}) @ResponseStatus(HttpStatus.CREATED) public HttpHeaders create(@RequestBody UserInput userInput) { … } @ExceptionHandler(IllegalArgumentException.class) private ResponseEntity<Void> handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.PAYMENT_REQUIRED); } It’s outright wrong
15. All the problems you have with JavaDoc
16. All the problems you have with JavaDoc — but worse.
17. "When did we start to equate „easy to create“ with „good“? Me
18. "Code generation – so that you can do the wrong thing faster… Kevlin Henney
19. What to
 do instead?
20. Write as much as possible in a format that’s designed for writing
21. Don’t use the implementation
 to provide the documentation blindly
22. Provide some guarantees that the documentation is accurate
23. TDD — Test-Driven Documentation
24. Asciidoctor Spring MVC Test Maven / Gradle spring-projects/spring-restdocs
25. Writing a test case… @Test public void index() throws Exception { this.mockMvc.perform(get("/")) .andExpect(status().isOk()) .andExpect(jsonPath("_links.notes", is(notNullValue()))) .andExpect(jsonPath("_links.tags", is(notNullValue()))) .andDo(document("index")); } 1 2 3 4
26. …creates a Asciidoctor cURL snippet… [source, bash] ---- $ curl 'http://localhost:8080/' -i ----
27. …creates a Asciidoctor cURL snippet…
28. … as well as a response one… [source, http] ---- HTTP/1.1 200 OK Content-Type: application/hal+json { "_links" : { "tags" : { "href" : "http://localhost:8080/tags" }, "notes" : { "href" : "http://localhost:8080/notes" } } ----
29. … as well as a response one…
30. Document links and payloads / responses this.mockMvc.perform(get("/")) .andExpect(status().isOk()) .andDo(document("index", links( linkWithRel("notes").description( "The <<resources-notes, Notes resource>>"), linkWithRel("tags").description( "The <<resources-tags, Tags resource>>") ), responseFields( fieldWithPath("_links").description( "<<resources-index-links,Links>> to other resources") ) )); 1 2 3
31. Document links and payloads / responses |=== | Relation | Description | notes | The <<resources-notes, Notes resource>> | tags | The <<resources-tags, Tags resource>> |===
32. Document links and payloads / responses
33. Document links and payloads / responses |=== |Path|Type|Description |_links |Object |<<resources-index-links,Links>> to other resources |===
34. Document links and payloads / responses
35. Demo
36. For more bliss, combine with
 HAL browser…
37. Demo
38. Resources Chatty42 — GitHub repository, App on Heroku Spring RESTDocs — GitHub repository Andy Wilkinson - Documenting RESTful APIs — Webinar recording