Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Support using alwaysDo to automatically document every MockMvc call

Browse Source 
The MVC test framework provides an alwaysDo method which allows the
configuration of a result handler to be that will be invoked for every
call to perform. Previously, this method could not be used for
producing documentation snippets as the snippets would overwrite each
other.

This commit adds support for writing snippets to a parameterized
output directory. Two parameters are supported: method name and step.
Method name is the name of the currently executing test method. Step
is a count of the number of calls to MockMvc.perform that have been
made in that method.

Closes gh-14
This commit is contained in:
Andy Wilkinson
2015-02-25 10:56:01 +00:00
parent 289ba57159
commit 1eeb605108
18 changed files with 681 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.asciidoc
View File

@@ -42,12 +42,12 @@ $ java -jar build/libs/*.jar
You can check that the service is up and running by executing a simple request using
cURL:
include::{generated}/index/request.asciidoc[]
include::{generated}/index/1/request.asciidoc[]
This request should yield the following response in the
http://stateless.co/hal_specification.html[Hypertext Application Language (HAL)] format:
include::{generated}/index/response.asciidoc[]
include::{generated}/index/1/response.asciidoc[]
Note the `_links` in the JSON response. They are key to navigating the API.
@@ -59,26 +59,26 @@ Now that you've started the service and verified that it works, the next step is
it to create a new note. As you saw above, the URI for working with notes is included as
a link when you perform a `GET` request against the root of the service:
include::{generated}/index/response.asciidoc[]
include::{generated}/index/1/response.asciidoc[]
To create a note, you need to execute a `POST` request to this URI including a JSON
payload containing the title and body of the note:
include::{generated}/create-note/request.asciidoc[]
include::{generated}/creating-a-note/1/request.asciidoc[]
The response from this request should have a status code of `201 Created` and contain a
`Location` header whose value is the URI of the newly created note:
include::{generated}/create-note/response.asciidoc[]
include::{generated}/creating-a-note/1/response.asciidoc[]
To work with the newly created note you use the URI in the `Location` header. For example,
you can access the note's details by performing a `GET` request:
include::{generated}/get-note/request.asciidoc[]
include::{generated}/creating-a-note/2/request.asciidoc[]
This request will produce a response with the note's details in its body:
include::{generated}/get-note/response.asciidoc[]
include::{generated}/creating-a-note/2/response.asciidoc[]
Note the `tags` link which we'll make use of later.
@@ -92,26 +92,26 @@ to tag a note, you must first create the tag.
Referring back to the response for the service's index, the URI for working with tags is
include as a link:
include::{generated}/index/response.asciidoc[]
include::{generated}/index/1/response.asciidoc[]
To create a tag you need to execute a `POST` request to this URI, including a JSON
payload containing the name of the tag:
include::{generated}/create-tag/request.asciidoc[]
include::{generated}/creating-a-note/3/request.asciidoc[]
The response from this request should have a status code of `201 Created` and contain a
`Location` header whose value is the URI of the newly created tag:
include::{generated}/create-tag/response.asciidoc[]
include::{generated}/creating-a-note/3/response.asciidoc[]
To work with the newly created tag you use the URI in the `Location` header. For example
you can access the tag's details by performing a `GET` request:
include::{generated}/get-tag/request.asciidoc[]
include::{generated}/creating-a-note/4/request.asciidoc[]
This request will produce a response with the tag's details in its body:
include::{generated}/get-tag/response.asciidoc[]
include::{generated}/creating-a-note/4/response.asciidoc[]
@@ -132,24 +132,24 @@ with it.
Once again we execute a `POST` request. However, this time, in an array named tags, we
include the URI of the tag we just created:
include::{generated}/create-tagged-note/request.asciidoc[]
include::{generated}/creating-a-note/5/request.asciidoc[]
Once again, the response's `Location` header tells us the URI of the newly created note:
include::{generated}/create-tagged-note/response.asciidoc[]
include::{generated}/creating-a-note/5/response.asciidoc[]
As before, a `GET` request executed against this URI will retrieve the note's details:
include::{generated}/get-tagged-note/request-response.asciidoc[]
include::{generated}/creating-a-note/6/request-response.asciidoc[]
To verify that the tag has been associated with the note, we can perform a `GET` request
against the URI from the `tags` link:
include::{generated}/get-tags/request.asciidoc[]
include::{generated}/creating-a-note/7/request.asciidoc[]
The response embeds information about the tag that we've just associated with the note:
include::{generated}/get-tags/response.asciidoc[]
include::{generated}/creating-a-note/7/response.asciidoc[]
@@ -159,17 +159,17 @@ An existing note can be tagged by executing a `PATCH` request against the note's
a body that contains the array of tags to be associated with the note. We'll used the
URI of the untagged note that we created earlier:
include::{generated}/tag-existing-note/request.asciidoc[]
include::{generated}/creating-a-note/8/request.asciidoc[]
This request should produce a `204 No Content` response:
include::{generated}/tag-existing-note/response.asciidoc[]
include::{generated}/creating-a-note/8/response.asciidoc[]
When we first created this note, we noted the tags link included in its details:
include::{generated}/get-note/response.asciidoc[]
include::{generated}/creating-a-note/2/response.asciidoc[]
We can use that link now and execute a `GET` request to see that the note now has a
single tag:
include::{generated}/get-tags-for-existing-note/request-response.asciidoc[]
include::{generated}/creating-a-note/9/request-response.asciidoc[]

1
samples/rest-notes-spring-data-rest/src/main/resources/application.properties Normal file
View File

@@ -0,0 +1 @@
spring.jackson.serialization.indent_output: true

2
samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java
View File

@@ -39,7 +39,7 @@ import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.SpringApplicationConfiguration;
import org.springframework.hateoas.MediaTypes;
import org.springframework.restdocs.RestDocumentationConfigurer;
import org.springframework.restdocs.config.RestDocumentationConfigurer;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;

95
samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/GettingStartedDocumentation.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014 the original author or authors.
* Copyright 2014-2015 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -38,7 +38,7 @@ import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.SpringApplicationConfiguration;
import org.springframework.hateoas.MediaTypes;
import org.springframework.restdocs.RestDocumentationConfigurer;
import org.springframework.restdocs.config.RestDocumentationConfigurer;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
@@ -66,33 +66,33 @@ public class GettingStartedDocumentation {
@Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(new RestDocumentationConfigurer()).build();
.apply(new RestDocumentationConfigurer())
.alwaysDo(document("{method-name}/{step}/"))
.build();
}
@Test
public void index() throws Exception {
this.mockMvc.perform(get("/").accept(MediaTypes.HAL_JSON))
.andExpect(status().isOk())
.andExpect(jsonPath("_links.notes", is(notNullValue())))
.andExpect(jsonPath("_links.tags", is(notNullValue())))
.andDo(document("index"));
.andExpect(status().isOk())
.andExpect(jsonPath("_links.notes", is(notNullValue())))
.andExpect(jsonPath("_links.tags", is(notNullValue())));
}
@Test
public void creatingANote() throws JsonProcessingException, Exception {
String noteLocation = createNote();
getNote(noteLocation);
MvcResult note = getNote(noteLocation);
String tagLocation = createTag();
getTag(tagLocation);
String taggedNoteLocation = createTaggedNote(tagLocation);
getTaggedNote(taggedNoteLocation);
getTags(taggedNoteLocation);
MvcResult taggedNote = getNote(taggedNoteLocation);
getTags(getLink(taggedNote, "tags"));
tagExistingNote(noteLocation, tagLocation);
getTaggedExistingNote(noteLocation);
getTagsForExistingNote(noteLocation);
getTags(getLink(note, "tags"));
}
String createNote() throws Exception {
@@ -106,18 +106,17 @@ public class GettingStartedDocumentation {
objectMapper.writeValueAsString(note)))
.andExpect(status().isCreated())
.andExpect(header().string("Location", notNullValue()))
.andDo(document("create-note"))
.andReturn().getResponse().getHeader("Location");
return noteLocation;
}
void getNote(String noteLocation) throws Exception {
this.mockMvc.perform(get(noteLocation))
.andExpect(status().isOk())
.andExpect(jsonPath("title", is(notNullValue())))
.andExpect(jsonPath("body", is(notNullValue())))
.andExpect(jsonPath("_links.tags", is(notNullValue())))
.andDo(document("get-note"));
MvcResult getNote(String noteLocation) throws Exception {
return this.mockMvc.perform(get(noteLocation))
.andExpect(status().isOk())
.andExpect(jsonPath("title", is(notNullValue())))
.andExpect(jsonPath("body", is(notNullValue())))
.andExpect(jsonPath("_links.tags", is(notNullValue())))
.andReturn();
}
String createTag() throws Exception, JsonProcessingException {
@@ -128,19 +127,16 @@ public class GettingStartedDocumentation {
.perform(
post("/tags").contentType(MediaTypes.HAL_JSON).content(
objectMapper.writeValueAsString(tag)))
.andExpect(status().isCreated())
.andExpect(header().string("Location", notNullValue()))
.andDo(document("create-tag"))
.andReturn().getResponse().getHeader("Location");
.andExpect(status().isCreated())
.andExpect(header().string("Location", notNullValue()))
.andReturn().getResponse().getHeader("Location");
return tagLocation;
}
void getTag(String tagLocation) throws Exception {
this.mockMvc.perform(get(tagLocation))
.andExpect(status().isOk())
this.mockMvc.perform(get(tagLocation)).andExpect(status().isOk())
.andExpect(jsonPath("name", is(notNullValue())))
.andExpect(jsonPath("_links.notes", is(notNullValue())))
.andDo(document("get-tag"));
.andExpect(jsonPath("_links.notes", is(notNullValue())));
}
String createTaggedNote(String tag) throws Exception {
@@ -155,28 +151,14 @@ public class GettingStartedDocumentation {
objectMapper.writeValueAsString(note)))
.andExpect(status().isCreated())
.andExpect(header().string("Location", notNullValue()))
.andDo(document("create-tagged-note"))
.andReturn().getResponse().getHeader("Location");
return noteLocation;
}
void getTaggedNote(String tagLocation) throws Exception {
this.mockMvc.perform(get(tagLocation))
void getTags(String noteTagsLocation) throws Exception {
this.mockMvc.perform(get(noteTagsLocation))
.andExpect(status().isOk())
.andExpect(jsonPath("title", is(notNullValue())))
.andExpect(jsonPath("body", is(notNullValue())))
.andExpect(jsonPath("_links.tags", is(notNullValue())))
.andDo(document("get-tagged-note"));
}
void getTags(String taggedNoteLocation) throws Exception {
String tagsLocation = getLink(this.mockMvc.perform(get(taggedNoteLocation))
.andReturn(), "tags");
this.mockMvc.perform(get(tagsLocation))
.andExpect(status().isOk())
.andExpect(jsonPath("_embedded.tags", hasSize(1)))
.andDo(document("get-tags"));
.andExpect(jsonPath("_embedded.tags", hasSize(1)));
}
void tagExistingNote(String noteLocation, String tagLocation) throws Exception {
@@ -186,29 +168,24 @@ public class GettingStartedDocumentation {
this.mockMvc.perform(
patch(noteLocation).contentType(MediaTypes.HAL_JSON).content(
objectMapper.writeValueAsString(update)))
.andExpect(status().isNoContent())
.andDo(document("tag-existing-note"));
.andExpect(status().isNoContent());
}
void getTaggedExistingNote(String tagLocation) throws Exception {
this.mockMvc.perform(get(tagLocation))
MvcResult getTaggedExistingNote(String noteLocation) throws Exception {
return this.mockMvc.perform(get(noteLocation))
.andExpect(status().isOk())
.andDo(document("get-tagged-existing-note"));
.andReturn();
}
void getTagsForExistingNote(String taggedNoteLocation) throws Exception {
String tagsLocation = getLink(this.mockMvc.perform(get(taggedNoteLocation))
.andReturn(), "tags");
this.mockMvc.perform(get(tagsLocation))
void getTagsForExistingNote(String noteTagsLocation) throws Exception {
this.mockMvc.perform(get(noteTagsLocation))
.andExpect(status().isOk())
.andExpect(jsonPath("_embedded.tags", hasSize(1)))
.andDo(document("get-tags-for-existing-note"));
.andExpect(jsonPath("_embedded.tags", hasSize(1)));
}
private String getLink(MvcResult result, String href)
private String getLink(MvcResult result, String rel)
throws UnsupportedEncodingException {
return JsonPath.parse(result.getResponse().getContentAsString()).read(
"_links.tags.href");
"_links." + rel + ".href");
}
}