Allow request and path parameters to be marked as optional

Closes gh-169

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);