Wie soll man das denn nutzen? Dokumentation von REST-Schnittstellen mit Spring REST Docs Gerrit Meier@JUG Saxony Day 2016

„Eine schöne RESTful-API haben Sie da, wäre ja traurig, wenn die keiner nutzen 
 würde.“

Problem: keine Dokumentation vorhanden

Lösung: Dokumentation nachholen

https://www.flickr.com/photos/whateverjamesinstitches/4623922729/

Senior Consultant
 T-Systems on site services GmbH 8 Jahre ‚professionell‘ Java JUG Ostfalen Co-Organisator Podcast meistermeier

Gibt es da nicht schon etwas?

Swagger

No content

@ApiOperation(nickname = "loginUser",
 value = "Logs user into the system", response = classOf[String], 
 httpMethod = "GET")
 @ApiResponses(Array(
 new ApiResponse(code = 400, message = "Invalid username and password combination")))
 def loginUser(
 @ApiParam(value = "The user name for login", required = true)
 username: String,
 @ApiParam(value = "The password for login in clear text", required = true) 
 password: String) = Action { 
 implicit request =>
 JsonResponse("logged in user session:" + System.currentTimeMillis())
 }


 @ApiOperation(nickname = "updateUser",
 value = "Updated user“, notes = "This can only be done by the logged in user.", httpMethod = "PUT")
 @ApiResponses(Array(
 new ApiResponse(code = 400, message = "Invalid username supplied"),
 new ApiResponse(code = 404, message = "User not found")))
 @ApiImplicitParams(Array(
 new ApiImplicitParam (name = "username", value = "name that need to be 
 updated", required = true, dataType = "String", paramType = "path"),
 new ApiImplicitParam(name = "body", value = "Updated user object",
 required = true, dataType = "models.User", paramType = "body")))
 def updateUser(username: String) = Action { implicit request =>
 request.body.asJson match {
 case Some(e) => {
 val user = Json.mapper.readValue(e.toString, classOf[User])
 userData.addUser(user)
 JsonResponse(user)
 }
 case None => JsonResponse(new value.ApiResponse(400, "Invalid input"))
 }
 }

https://www.flickr.com/photos/endless_autumn/2820524593

Das Problem von Dokumentation am 
 Code ist, dass sie veralten wird.

@ApiResponses(
 value = {
 @ApiResponse(code = 200, message = "leaking resource available"),
 @ApiResponse(code = 404, message = "cannot find leaking resource"),
 }
 )
 public Status getLeakingInformation() {
 return new Status(200);
 }

@ApiResponses(
 value = {
 @ApiResponse(code = 200, message = "leaking resource available"),
 @ApiResponse(code = 404, message = "cannot find leaking resource"),
 }
 )
 public Status getLeakingInformation() {
 return new Status(451);
 }

No content

http://martinfowler.com/articles/richardsonMaturityModel.html The Swamp of POX Resources HTTP Verbs Hypermedia Controls

No content

Spring REST Docs

No content

{
 "_links" : {
 "breweries" : {
 "href" : "http://localhost:8888/breweries"
 },
 "beers" : {
 "href" : "http://localhost:8888/beers"
 },
 "profile" : {
 "href" : "http://localhost:8888/profile"
 }
 }
 } $ curl 'http://localhost:8080/' -i

@Test
 public void index() throws Exception {
 mockMvc.perform(RestDocumentationRequestBuilders.get(„/")) .andExpect(MockMvcResultMatchers.status().isOk())
 .andDo( document("index-page", links(
 linkWithRel("breweries").
 description("The <>“),
 linkWithRel("beers").description("The <>"),
 linkWithRel("profile").description("The ALPS profile for the service")
 ), responseFields( fieldWithPath("_links")
 .description("<> to other resources“) )
 ));
 }

@Test
 public void index() throws Exception {
 mockMvc.perform(RestDocumentationRequestBuilders.get(„/")) .andExpect(MockMvcResultMatchers.status().isOk())
 .andDo( document("index-page", links(
 linkWithRel("breweries").
 description("The <>“),
 linkWithRel("beers").description("The <>"),
 linkWithRel("profile").description("The ALPS profile for the service")
 ), responseFields( fieldWithPath("_links")
 .description("<> to other resources“) )
 ));
 }

@Test
 public void index() throws Exception {
 mockMvc.perform(RestDocumentationRequestBuilders.get(„/")) .andExpect(MockMvcResultMatchers.status().isOk())
 .andDo( document("index-page", links(
 linkWithRel("breweries").
 description("The <>“),
 linkWithRel("beers").description("The <>"),
 linkWithRel("profile").description("The ALPS profile for the service")
 ), responseFields( fieldWithPath("_links")
 .description("<> to other resources“) )
 ));
 }

No content

No content

No content

No content

No content

No content

No content

include::

No content

DEMO

meistermeier https://projects.spring.io/spring-restdocs/ https://github.com/spring-projects/spring-restdocs https://github.com/meistermeier/spring-rest-docs-sample