Allow documentation of extra attributes that apply to the whole snippet

This commit adds support for associating custom attributes with the
generation of a particular snippet. The attributes are included in
the model during snippet rendering allowing them to be referenced from
a custom snippet template. Among other things, this makes it possible
to provide a configurable title for snippets that produce a code
block.

Closes gh-77

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -283,39 +283,52 @@ override the template for the `curl-request.adoc` snippet, create a template nam
 
 [[documenting-your-api-customizing-including-extra-information]]
 ==== Including extra information
-The descriptors for fields, links, and query parameters all have an `attribute` method
-that can be used to associate one or more key-value pairs with the descriptor. These
-attributes are made available during the template rendering process. Coupled with
-a custom snippet template, this makes it possible to include extra information in a
-generated snippet.
 
-A concrete example of the above is the addition of a constraints column when documenting
-request fields. The first step is to provide a `constraints` attribute for each field that
-you are documenting:
+There are two ways to provide extra information for inclusion in a generated snippet:
+
+. Use the `attributes` method on a field, link or query parameter descriptor to add one or
+  more attributes to an individual descriptor
+. Pass in some attributes when calling `withCurlRequest`, `withHttpRequest`,
+  `withHttpResponse`, etc on `RestDocumentationResultHandler`. Such attributes will be
+  associated with the snippet as a whole.
+
+Any additional attributes are made available during the template rendering process.
+Coupled with a custom snippet template, this makes it possible to include extra
+information in a generated snippet.
+
+A concrete example of the above is the addition of a constraints column and a title when
+documenting request fields. The first step is to provide a `constraints` attribute for
+each field that you are documenting and to provide a `title` attribute:
 
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/Payload.java[tags=constraints]
 ----
+<1> Configure the `title` attribute for the request fields snippet
+<2> Set the `constraints` attribute for the `name` field
+<3> Set the `constraints` attribute for the `email` field
 
 The second step is to provide a custom template named `request-fields.snippet` that
-includes the information about the fields' constraints in the generated snippet's table:
+includes the information about the fields' constraints in the generated snippet's table
+and adds a title:
 
 [source,indent=0]
 ----
+	.{{title}} <1>
 	|===
-	|Path|Type|Description|Constraints <1>
+	|Path|Type|Description|Constraints <2>
 
 	{{#fields}}
 	|{{path}}
 	|{{type}}
 	|{{description}}
-	|{{constraints}} <2>
+	|{{constraints}} <3>
 
 	{{/fields}}
 	|===
 ----
-<1> Add a new column named "Constraints"
-<2> Include the descriptors' `constraints` attribute in each row of the table
+<1> Add a title to the table
+<2> Add a new column named "Constraints"
+<3> Include the descriptors' `constraints` attribute in each row of the table
 
 

docs/src/test/java/com/example/Payload.java

@@ -17,12 +17,16 @@
 package com.example;
 
 import static org.springframework.restdocs.RestDocumentation.document;
+import static org.springframework.restdocs.Attributes.attributes;
+import static org.springframework.restdocs.Attributes.key;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+import static org.springframework.restdocs.Attributes.key;
 
 import org.springframework.http.MediaType;
+import org.springframework.restdocs.Attributes;
 import org.springframework.restdocs.payload.FieldType;
 import org.springframework.test.web.servlet.MockMvc;
 
@@ -57,12 +61,16 @@ private MockMvc mockMvc;
 			.andExpect(status().isOk())
 			// tag::constraints[]
 			.andDo(document("create-user").withRequestFields(
+					attributes(
+							key("title").value("Fields for user creation")), // <1>
 					fieldWithPath("name")
 							.description("The user's name")
-							.attribute("constraints", "Must not be null. Must not be empty"),
+							.attributes(
+									key("constraints").value("Must not be null. Must not be empty")), // <2>
 					fieldWithPath("email")
 							.description("The user's email address")
-							.attribute("constrains", "Must be a valid email address")));
+							.attributes(
+									key("constraints").value("Must be a valid email address")))); // <3>
 			// end::constraints[]
 	}