Allow request and path parameters to be marked as optional

Closes gh-169

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

@@ -348,7 +348,8 @@ table describing the parameters that are supported by the resource.
 
 When documenting request parameters, the test will fail if an undocumented request
 parameter is used in the request. Similarly, the test will also fail if a documented
-request parameter is not found in the request.
+request parameter is not found in the request and the request parameter has not been
+marked as optional.
 
 If you do not want to document a request parameter, you can mark it as ignored. This will
 prevent it from appearing in the generated snippet while avoiding the failure described
@@ -396,7 +397,7 @@ built using one of the methods on `RestDocumentationRequestBuilders` rather than
 
 When documenting path parameters, the test will fail if an undocumented path parameter
 is used in the request. Similarly, the test will also fail if a documented path parameter
-is not found in the request.
+is not found in the request and the path parameter has not been marked as optional.
 
 If you do not want to document a path parameter, you can mark it as ignored. This will
 prevent it from appearing in the generated snippet while avoiding the failure described

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/AbstractParametersSnippet.java

@@ -85,7 +85,13 @@ public abstract class AbstractParametersSnippet extends TemplatedSnippet {
 
 	private void verifyParameterDescriptors(Operation operation) {
 		Set<String> actualParameters = extractActualParameters(operation);
-		Set<String> expectedParameters = this.descriptorsByName.keySet();
+		Set<String> expectedParameters = new HashSet<>();
+		for (Entry<String, ParameterDescriptor> entry : this.descriptorsByName
+				.entrySet()) {
+			if (!entry.getValue().isOptional()) {
+				expectedParameters.add(entry.getKey());
+			}
+		}
 		Set<String> undocumentedParameters = new HashSet<>(actualParameters);
 		undocumentedParameters.removeAll(expectedParameters);
 		Set<String> missingParameters = new HashSet<>(expectedParameters);

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/ParameterDescriptor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 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.
@@ -29,6 +29,8 @@ public class ParameterDescriptor extends IgnorableDescriptor<ParameterDescriptor
 
 	private final String name;
 
+	private boolean optional;
+
 	/**
 	 * Creates a new {@code ParameterDescriptor} describing the parameter with the given
 	 * {@code name}.
@@ -39,6 +41,16 @@ public class ParameterDescriptor extends IgnorableDescriptor<ParameterDescriptor
 		this.name = name;
 	}
 
+	/**
+	 * Marks the parameter as optional.
+	 *
+	 * @return {@code this}
+	 */
+	public final ParameterDescriptor optional() {
+		this.optional = true;
+		return this;
+	}
+
 	/**
 	 * Returns the name of the parameter being described by this descriptor.
 	 *
@@ -48,4 +60,15 @@ public class ParameterDescriptor extends IgnorableDescriptor<ParameterDescriptor
 		return this.name;
 	}
 
+	/**
+	 * Returns {@code true} if the described parameter is optional, otherwise
+	 * {@code false}.
+	 *
+	 * @return {@code true} if the described parameter is optional, otherwise
+	 * {@code false}
+	 */
+	public final boolean isOptional() {
+		return this.optional;
+	}
+
 }

spring-restdocs-core/src/test/java/org/springframework/restdocs/request/PathParametersSnippetTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 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.
@@ -71,6 +71,22 @@ public class PathParametersSnippetTests extends AbstractSnippetTests {
 								"/{a}/{b}").build());
 	}
 
+	@Test
+	public void missingOptionalPathParameter() throws IOException {
+		this.snippet
+				.expectPathParameters(
+						"missing-optional-path-parameter")
+				.withContents(tableWithTitleAndHeader(
+						this.templateFormat == TemplateFormats.asciidoctor() ? "/{a}"
+								: "`/{a}`",
+						"Parameter", "Description").row("a", "one").row("b", "two"));
+		new PathParametersSnippet(Arrays.asList(parameterWithName("a").description("one"),
+				parameterWithName("b").description("two").optional())).document(
+						operationBuilder("missing-optional-path-parameter").attribute(
+								RestDocumentationGenerator.ATTRIBUTE_NAME_URL_TEMPLATE,
+								"/{a}").build());
+	}
+
 	@Test
 	public void pathParametersWithQueryString() throws IOException {
 		this.snippet.expectPathParameters("path-parameters-with-query-string")

spring-restdocs-core/src/test/java/org/springframework/restdocs/request/RequestParametersSnippetTests.java

@@ -80,6 +80,19 @@ public class RequestParametersSnippetTests extends AbstractSnippetTests {
 								.param("b", "bravo").build());
 	}
 
+	@Test
+	public void missingOptionalRequestParameter() throws IOException {
+		this.snippet.expectRequestParameters("missing-optional-request-parameter")
+				.withContents(tableWithHeader("Parameter", "Description").row("a", "one")
+						.row("b", "two"));
+		new RequestParametersSnippet(
+				Arrays.asList(parameterWithName("a").description("one").optional(),
+						parameterWithName("b").description("two"))).document(
+								operationBuilder("missing-optional-request-parameter")
+										.request("http://localhost").param("b", "bravo")
+										.build());
+	}
+
 	@Test
 	public void requestParametersWithCustomAttributes() throws IOException {
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);