Rework the API to improve readability and extensibility

This commit updates the API to improve its extensibility and
readability.

SnippetWritingResultHandler has been replaced with a  more general
purpose Snippet interface. Snippets are now provided to the main
document method using varargs rather than the various with… methods
that were previously used. As a result a custom Snippet implementation
can now be used in exactly the same way as any of the built-in
snippets:

this.mockMvc.perform(get("/"))
        .andExpect(status().isOk())
        .andDo(document("index-example",
                links(
                        linkWithRel("notes").description("…"),
                        linkWithRel("tags").description("…")),
                responseFields(
                        fieldWithPath("_links").description("…")),
                yourCustomSnippet()));

Control of the snippets that are generated by default is now available
via RestDocumentationConfigurer:

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
        .apply(documentationConfiguration().snippets()
               .withDefaults(curlRequest(), yourCustomSnippet()))
        .build();

See gh-73

samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java

@@ -21,7 +21,10 @@ import static org.hamcrest.Matchers.notNullValue;
 import static org.springframework.restdocs.RestDocumentation.document;
 import static org.springframework.restdocs.RestDocumentation.documentationConfiguration;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
+import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
+import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
 import static org.springframework.restdocs.RestDocumentationRequestBuilders.patch;
 import static org.springframework.restdocs.RestDocumentationRequestBuilders.post;
@@ -89,25 +92,25 @@ public class ApiDocumentation {
 			.andExpect(jsonPath("timestamp", is(notNullValue())))
 			.andExpect(jsonPath("status", is(400)))
 			.andExpect(jsonPath("path", is(notNullValue())))
-			.andDo(document("error-example")
-					.withResponseFields(
+			.andDo(document("error-example",
+					responseFields(
 							fieldWithPath("error").description("The HTTP error that occurred, e.g. `Bad Request`"),
 							fieldWithPath("message").description("A description of the cause of the error"),
 							fieldWithPath("path").description("The path to which the request was made"),
 							fieldWithPath("status").description("The HTTP status code, e.g. `400`"),
-							fieldWithPath("timestamp").description("The time, in milliseconds, at which the error occurred")));
+							fieldWithPath("timestamp").description("The time, in milliseconds, at which the error occurred"))));
 	}
 
 	@Test
 	public void indexExample() throws Exception {
 		this.mockMvc.perform(get("/"))
 			.andExpect(status().isOk())
-			.andDo(document("index-example")
-					.withLinks(
+			.andDo(document("index-example",
+					links(
 							linkWithRel("notes").description("The <<resources-notes,Notes resource>>"),
-							linkWithRel("tags").description("The <<resources-tags,Tags resource>>"))
-					.withResponseFields(
-							fieldWithPath("_links").description("<<resources-index-links,Links>> to other resources")));
+							linkWithRel("tags").description("The <<resources-tags,Tags resource>>")),
+					responseFields(
+							fieldWithPath("_links").description("<<resources-index-links,Links>> to other resources"))));
 	}
 
 	@Test
@@ -122,9 +125,9 @@ public class ApiDocumentation {
 
 		this.mockMvc.perform(get("/notes"))
 			.andExpect(status().isOk())
-			.andDo(document("notes-list-example")
-					.withResponseFields(
-							fieldWithPath("_embedded.notes").description("An array of <<resources-note, Note resources>>")));
+			.andDo(document("notes-list-example",
+					responseFields(
+							fieldWithPath("_embedded.notes").description("An array of <<resources-note, Note resources>>"))));
 	}
 
 	@Test
@@ -148,11 +151,11 @@ public class ApiDocumentation {
 				post("/notes").contentType(MediaTypes.HAL_JSON).content(
 						this.objectMapper.writeValueAsString(note)))
 				.andExpect(status().isCreated())
-				.andDo(document("notes-create-example")
-						.withRequestFields(
+				.andDo(document("notes-create-example",
+						requestFields(
 								fieldWithPath("title").description("The title of the note"),
 								fieldWithPath("body").description("The body of the note"),
-								fieldWithPath("tags").description("An array of tag resource URIs")));
+								fieldWithPath("tags").description("An array of tag resource URIs"))));
 	}
 
 	@Test
@@ -185,14 +188,14 @@ public class ApiDocumentation {
 			.andExpect(jsonPath("body", is(note.get("body"))))
 			.andExpect(jsonPath("_links.self.href", is(noteLocation)))
 			.andExpect(jsonPath("_links.note-tags", is(notNullValue())))
-			.andDo(document("note-get-example")
-					.withLinks(
+			.andDo(document("note-get-example",
+					links(
 							linkWithRel("self").description("This <<resources-note,note>>"),
-							linkWithRel("note-tags").description("This note's <<resources-note-tags,tags>>"))
-					.withResponseFields(
+							linkWithRel("note-tags").description("This note's <<resources-note-tags,tags>>")),
+					responseFields(
 							fieldWithPath("title").description("The title of the note"),
 							fieldWithPath("body").description("The body of the note"),
-							fieldWithPath("_links").description("<<resources-note-links,Links>> to other resources")));
+							fieldWithPath("_links").description("<<resources-note-links,Links>> to other resources"))));
 
 	}
 
@@ -207,9 +210,9 @@ public class ApiDocumentation {
 
 		this.mockMvc.perform(get("/tags"))
 			.andExpect(status().isOk())
-			.andDo(document("tags-list-example")
-					.withResponseFields(
-							fieldWithPath("_embedded.tags").description("An array of <<resources-tag,Tag resources>>")));
+			.andDo(document("tags-list-example",
+					responseFields(
+							fieldWithPath("_embedded.tags").description("An array of <<resources-tag,Tag resources>>"))));
 	}
 
 	@Test
@@ -221,9 +224,9 @@ public class ApiDocumentation {
 				post("/tags").contentType(MediaTypes.HAL_JSON).content(
 						this.objectMapper.writeValueAsString(tag)))
 				.andExpect(status().isCreated())
-				.andDo(document("tags-create-example")
-						.withRequestFields(
-								fieldWithPath("name").description("The name of the tag")));
+				.andDo(document("tags-create-example",
+						requestFields(
+								fieldWithPath("name").description("The name of the tag"))));
 	}
 
 	@Test
@@ -262,11 +265,11 @@ public class ApiDocumentation {
 				patch(noteLocation).contentType(MediaTypes.HAL_JSON).content(
 						this.objectMapper.writeValueAsString(noteUpdate)))
 				.andExpect(status().isNoContent())
-				.andDo(document("note-update-example")
-						.withRequestFields(
+				.andDo(document("note-update-example",
+						requestFields(
 								fieldWithPath("title").description("The title of the note").type(FieldType.STRING).optional(),
 								fieldWithPath("body").description("The body of the note").type(FieldType.STRING).optional(),
-								fieldWithPath("tags").description("An array of tag resource URIs").optional()));
+								fieldWithPath("tags").description("An array of tag resource URIs").optional())));
 	}
 
 	@Test
@@ -284,13 +287,13 @@ public class ApiDocumentation {
 		this.mockMvc.perform(get(tagLocation))
 			.andExpect(status().isOk())
 			.andExpect(jsonPath("name", is(tag.get("name"))))
-			.andDo(document("tag-get-example")
-					.withLinks(
+			.andDo(document("tag-get-example",
+					links(
 							linkWithRel("self").description("This <<resources-tag,tag>>"),
-							linkWithRel("tagged-notes").description("The <<resources-tagged-notes,notes>> that have this tag"))
-					.withResponseFields(
+							linkWithRel("tagged-notes").description("The <<resources-tagged-notes,notes>> that have this tag")),
+					responseFields(
 							fieldWithPath("name").description("The name of the tag"),
-							fieldWithPath("_links").description("<<resources-tag-links,Links>> to other resources")));
+							fieldWithPath("_links").description("<<resources-tag-links,Links>> to other resources"))));
 	}
 
 	@Test
@@ -312,9 +315,9 @@ public class ApiDocumentation {
 				patch(tagLocation).contentType(MediaTypes.HAL_JSON).content(
 						this.objectMapper.writeValueAsString(tagUpdate)))
 				.andExpect(status().isNoContent())
-				.andDo(document("tag-update-example")
-						.withRequestFields(
-								fieldWithPath("name").description("The name of the tag")));
+				.andDo(document("tag-update-example",
+						requestFields(
+								fieldWithPath("name").description("The name of the tag"))));
 	}
 
 	private void createNote(String title, String body) {