Allow request and path parameters to be marked as optional

Closes gh-169

Author: wilkinsona

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 @@ protected Map<String, Object> createModel(Operation operation) {
 
 	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 @@ protected ParameterDescriptor(String name) {
 		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 final String getName() {
 		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 void ignoredPathParameter() throws IOException {
 								"/{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 void ignoredRequestParameter() throws IOException {
 								.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);