Allow documentation of extra attributes on fields, links, and query parameters

This commit adds support for associating custom attributes with field,
link, and query parameter descriptors. These attributes are then
included in the model during snippet rendering. Coupled with a custom
snippet template, this enables the inclusion of extra column(s) in the
generated tables.

Closes gh-70

docs/src/docs/asciidoc/customizing-snippets.adoc

@@ -1,12 +0,0 @@
-[[customizing-snippets]]
-== Customizing the generated snippets
-
-Spring REST Docs uses https://mustache.github.io[Mustache] templates to produce the
-generated snippets. You can customize the generated snippets by overriding the
-{source}spring-restdocs/src/main/resources/org/springframework/restdocs/templates[default
-templates].
-
-Templates are loaded from the classpath in the `org.springframework.restdocs.templates`
-package and each template is named after the snippet that it will produce. For example, to
-override the template for the `curl-request.adoc` snippet, create a template named
-`curl-request.snippet` in `src/test/resources/org/springframework/restdocs/templates`.

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

@@ -257,4 +257,65 @@ include::{examples-dir}/com/example/AlwaysDo.java[tags=always-do]
 With this configuration in place, every call to `MockMvc.perform` will produce
 the <<documenting-your-api-default-snippets,default snippets>> without any further
 configuration. Take a look at the `GettingStartedDocumentation` classes in each of the
-sample applications to see this functionality in action.
+sample applications to see this functionality in action.
+
+
+
+[[documenting-your-api-customizing]]
+=== Customizing the output
+
+
+
+[[documenting-your-api-customizing-snippets]]
+==== Customizing the generated snippets
+Spring REST Docs uses https://mustache.github.io[Mustache] templates to produce the
+generated snippets.
+{source}spring-restdocs/src/main/resources/org/springframework/restdocs/templates[Default
+templates] are provided for each of the snippets that Spring REST Docs can produce. To
+customize a snippet's content, you can provide your own template.
+
+Templates are loaded from the classpath in the `org.springframework.restdocs.templates`
+package and each template is named after the snippet that it will produce. For example, to
+override the template for the `curl-request.adoc` snippet, create a template named
+`curl-request.snippet` in `src/test/resources/org/springframework/restdocs/templates`.
+
+
+
+[[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:
+
+[source,java,indent=0]
+----
+include::{examples-dir}/com/example/Payload.java[tags=constraints]
+----
+
+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:
+
+[source,indent=0]
+----
+	|===
+	|Path|Type|Description|Constraints <1>
+
+	{{#fields}}
+	|{{path}}
+	|{{type}}
+	|{{description}}
+	|{{constraints}} <2>
+
+	{{/fields}}
+	|===
+----
+<1> Add a new column named "Constraints"
+<2> Include the descriptors' `constraints` attribute in each row of the table
+
+

docs/src/docs/asciidoc/index.adoc

@@ -24,7 +24,6 @@ include::introduction.adoc[]
 include::getting-started.adoc[]
 include::documenting-your-api.adoc[]
 include::customizing-responses.adoc[]
-include::customizing-snippets.adoc[]
 include::configuration.adoc[]
 include::working-with-asciidoctor.adoc[]
 include::contributing.adoc[]

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

@@ -19,6 +19,7 @@ package com.example;
 import static org.springframework.restdocs.RestDocumentation.document;
 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 org.springframework.http.MediaType;
@@ -51,4 +52,18 @@ private MockMvc mockMvc;
 			// end::explicit-type[]
 	}
 
+	public void constraints() throws Exception {
+		this.mockMvc.perform(post("/users/").accept(MediaType.APPLICATION_JSON))
+			.andExpect(status().isOk())
+			// tag::constraints[]
+			.andDo(document("create-user").withRequestFields(
+					fieldWithPath("name")
+							.description("The user's name")
+							.attribute("constraints", "Must not be null. Must not be empty"),
+					fieldWithPath("email")
+							.description("The user's email address")
+							.attribute("constrains", "Must be a valid email address")));
+			// end::constraints[]
+	}
+
 }