Spring REST Docs DOCUMENTING RESTFUL APIS / @OLIVERGIERKE / @ANKINSON

No content

Hypermedia Documenting
 APIs?

Let’s use
 code
 generation!

Meet:
 Swagger…

It’s URI centric

Baking URIs into clients breaks independent deployability

It doesn’t support hypermedia https://github.com/swagger-api/swagger-core/issues/97

Always playing catch up – ResponseEntity https://github.com/springfox/springfox/issues/532

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) { … }

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 handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.BAD_REQUEST); }

@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 handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.BAD_REQUEST); } 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 handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.BAD_REQUEST); } 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 handleIllegalArgumentException() { return new ResponseEntity<>(HttpStatus.PAYMENT_REQUIRED); } It’s outright wrong

All the problems you have with JavaDoc

All the problems you have with JavaDoc — but worse.

"When did we start to equate „easy to create“ with „good“? Me

"Code generation – so that you can do the wrong thing faster… Kevlin Henney

What to
 do instead?

Write as much as possible in a format that’s designed for writing

Don’t use the implementation
 to provide the documentation blindly

Provide some guarantees that the documentation is accurate

TDD — Test-Driven Documentation

Asciidoctor Spring MVC Test Maven / Gradle spring-projects/spring-restdocs

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

…creates a Asciidoctor cURL snippet… [source, bash] ---- $ curl 'http://localhost:8080/' -i ----

…creates a Asciidoctor cURL snippet…

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

… as well as a response one…

Document links and payloads / responses this.mockMvc.perform(get("/")) .andExpect(status().isOk()) .andDo(document("index", links( linkWithRel("notes").description( "The <>"), linkWithRel("tags").description( "The <>") ), responseFields( fieldWithPath("_links").description( "<> to other resources") ) )); 1 2 3

Document links and payloads / responses |=== | Relation | Description | notes | The <> | tags | The <> |===

Document links and payloads / responses

Document links and payloads / responses |=== |Path|Type|Description |_links |Object |<> to other resources |===

Document links and payloads / responses

Demo

For more bliss, combine with
 HAL browser…

Demo

Resources Chatty42 — GitHub repository, App on Heroku Spring RESTDocs — GitHub repository Andy Wilkinson - Documenting RESTful APIs — Webinar recording