Handle form and query parameters separately

Previously, form and query parameters were handled together as
request parameters. Howeer, request parameters are a server-side
construct that's specific to the servlet specification. As such
they're not appropriate for the client-side documentation that
Spring REST Docs aims to produce.

This commit replaces support for documenting request parameters
with support for documenting query paramters found in the query
string of the request's URI and for documenting form parameters
found in the form URL encoded body of the request.

Closes gh-832

Author: wilkinsona

Diff for: docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -649,85 +649,110 @@ For example, the preceding code results in a snippet named `response-fields-bene
 
 
 
-[[documenting-your-api-request-parameters]]
-=== Request Parameters
+[[documenting-your-api-query-parameters]]
+=== Query Parameters
 
-You can document a request's parameters by using `requestParameters`.
-You can include request parameters in a `GET` request's query string.
+You can document a request's query parameters by using `queryParameters`.
 The following examples show how to do so:
 
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
-include::{examples-dir}/com/example/mockmvc/RequestParameters.java[tags=request-parameters-query-string]
+include::{examples-dir}/com/example/mockmvc/QueryParameters.java[tags=query-parameters]
 ----
 <1> Perform a `GET` request with two parameters, `page` and `per_page`, in the query string.
-<2> Configure Spring REST Docs to produce a snippet describing the request's parameters.
-Uses the static `requestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<2> Configure Spring REST Docs to produce a snippet describing the request's query parameters.
+Uses the static `queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <3> Document the `page` parameter.
 Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <4> Document the `per_page` parameter.
 
 [source,java,indent=0,role="secondary"]
 .WebTestClient
 ----
-include::{examples-dir}/com/example/webtestclient/RequestParameters.java[tags=request-parameters-query-string]
+include::{examples-dir}/com/example/webtestclient/QueryParameters.java[tags=query-parameters]
 ----
 <1> Perform a `GET` request with two parameters, `page` and `per_page`, in the query string.
-<2> Configure Spring REST Docs to produce a snippet describing the request's parameters.
-Uses the static `requestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<2> Configure Spring REST Docs to produce a snippet describing the request's query parameters.
+Uses the static `queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <3> Document the `page` parameter.
 Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <4> Document the `per_page` parameter.
 
 [source,java,indent=0,role="secondary"]
 .REST Assured
 ----
-include::{examples-dir}/com/example/restassured/RequestParameters.java[tags=request-parameters-query-string]
+include::{examples-dir}/com/example/restassured/QueryParameters.java[tags=query-parameters]
 ----
-<1> Configure Spring REST Docs to  produce a snippet describing the request's parameters.
-Uses the static `requestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<1> Configure Spring REST Docs to produce a snippet describing the request's query parameters.
+Uses the static `queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <2> Document the `page` parameter.
 Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <3> Document the `per_page` parameter.
 <4> Perform a `GET` request with two parameters, `page` and `per_page`, in the query string.
 
-You can also include request parameters as form data in the body of a POST request.
+When documenting query parameters, the test fails if an undocumented query parameter is used in the request's query string.
+Similarly, the test also fails if a documented query parameter is not found in the request's query string and the parameter has not been marked as optional.
+
+If you do not want to document a query parameter, you can mark it as ignored.
+This prevents it from appearing in the generated snippet while avoiding the failure described above.
+
+You can also document query parameters in a relaxed mode where any undocumented parameters do not cause a test failure.
+To do so, use the `relaxedQueryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+This can be useful when documenting a particular scenario where you only want to focus on a subset of the query parameters.
+
+
+
+[[documenting-your-api-form-parameters]]
+=== Form Parameters
+
+You can document a request's form parameters by using `formParameters`.
 The following examples show how to do so:
 
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
-include::{examples-dir}/com/example/mockmvc/RequestParameters.java[tags=request-parameters-form-data]
+include::{examples-dir}/com/example/mockmvc/FormParameters.java[tags=form-parameters]
 ----
-<1> Perform a `POST` request with a single parameter, `username`.
+<1> Perform a `POST` request with a single form parameter, `username`.
+<2> Configure Spring REST Docs to produce a snippet describing the request's form parameters.
+Uses the static `formParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<3> Document the `username` parameter.
+Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 
 [source,java,indent=0,role="secondary"]
 .WebTestClient
 ----
-include::{examples-dir}/com/example/webtestclient/RequestParameters.java[tags=request-parameters-form-data]
+include::{examples-dir}/com/example/webtestclient/FormParameters.java[tags=form-parameters]
 ----
-<1> Perform a `POST` request with a single parameter, `username`.
+<1> Perform a `POST` request with a single form parameter, `username`.
+<2> Configure Spring REST Docs to produce a snippet describing the request's form parameters.
+Uses the static `formParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<3> Document the `username` parameter.
+Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 
 [source,java,indent=0,role="secondary"]
 .REST Assured
 ----
-include::{examples-dir}/com/example/restassured/RequestParameters.java[tags=request-parameters-form-data]
+include::{examples-dir}/com/example/restassured/FormParameters.java[tags=form-parameters]
 ----
-<1> Configure the `username` parameter.
-<2> Perform the `POST` request.
+<1> Configure Spring REST Docs to produce a snippet describing the request's form parameters.
+Uses the static `formParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<2> Document the `username` parameter.
+Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
+<3> Perform a `POST` request with a single form parameter, `username`.
 
-In all cases, the result is a snippet named `request-parameters.adoc` that contains a table describing the parameters that are supported by the resource.
+In all cases, the result is a snippet named `form-parameters.adoc` that contains a table describing the form parameters that are supported by the resource.
 
-When documenting request parameters, the test fails if an undocumented request parameter is used in the request.
-Similarly, the test also fails if a documented request parameter is not found in the request and the request parameter has not been marked as optional.
+When documenting form parameters, the test fails if an undocumented form parameter is used in the request body.
+Similarly, the test also fails if a documented form parameter is not found in the request body and the form parameter has not been marked as optional.
 
-If you do not want to document a request parameter, you can mark it as ignored.
+If you do not want to document a form parameter, you can mark it as ignored.
 This prevents it from appearing in the generated snippet while avoiding the failure described above.
 
-You can also document request parameters in a relaxed mode where any undocumented parameters do not cause a test failure.
-To do so, use the `relaxedRequestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
-This can be useful when documenting a particular scenario where you only want to focus on a subset of the request parameters.
+You can also document form parameters in a relaxed mode where any undocumented parameters do not cause a test failure.
+To do so, use the `relaxedFormParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
+This can be useful when documenting a particular scenario where you only want to focus on a subset of the form parameters.
 
 
 

Diff for: docs/src/test/java/com/example/mockmvc/FormParameters.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2014-2021 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.mockmvc;
+
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.request.RequestDocumentation.formParameters;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+public class FormParameters {
+
+	private MockMvc mockMvc;
+
+	public void postFormDataSnippet() throws Exception {
+		// tag::form-parameters[]
+		this.mockMvc.perform(post("/users").param("username", "Tester")) // <1>
+				.andExpect(status().isCreated()).andDo(document("create-user", formParameters(// <2>
+						parameterWithName("username").description("The user's username") // <3>
+				)));
+		// end::form-parameters[]
+	}
+
+}

Diff for: docs/src/test/java/com/example/mockmvc/RequestParameters.java renamed to docs/src/test/java/com/example/mockmvc/QueryParameters.java

@@ -20,31 +20,22 @@
 
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
-import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
 import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
-import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
+import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
-public class RequestParameters {
+public class QueryParameters {
 
 	private MockMvc mockMvc;
 
 	public void getQueryStringSnippet() throws Exception {
-		// tag::request-parameters-query-string[]
+		// tag::query-parameters[]
 		this.mockMvc.perform(get("/users?page=2&per_page=100")) // <1>
-				.andExpect(status().isOk()).andDo(document("users", requestParameters(// <2>
+				.andExpect(status().isOk()).andDo(document("users", queryParameters(// <2>
 						parameterWithName("page").description("The page to retrieve"), // <3>
 						parameterWithName("per_page").description("Entries per page") // <4>
 				)));
-		// end::request-parameters-query-string[]
-	}
-
-	public void postFormDataSnippet() throws Exception {
-		// tag::request-parameters-form-data[]
-		this.mockMvc.perform(post("/users").param("username", "Tester")) // <1>
-				.andExpect(status().isCreated()).andDo(document("create-user",
-						requestParameters(parameterWithName("username").description("The user's username"))));
-		// end::request-parameters-form-data[]
+		// end::query-parameters[]
 	}
 
 }

Diff for: docs/src/test/java/com/example/restassured/FormParameters.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2014-2022 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.restassured;
+
+import io.restassured.RestAssured;
+import io.restassured.specification.RequestSpecification;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.springframework.restdocs.request.RequestDocumentation.formParameters;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document;
+
+public class FormParameters {
+
+	private RequestSpecification spec;
+
+	public void postFormDataSnippet() {
+		// tag::form-parameters[]
+		RestAssured.given(this.spec).filter(document("create-user", formParameters(// <1>
+				parameterWithName("username").description("The user's username")))) // <2>
+				.formParam("username", "Tester").when().post("/users") // <3>
+				.then().assertThat().statusCode(is(200));
+		// end::form-parameters[]
+	}
+
+}

Diff for: docs/src/test/java/com/example/restassured/RequestParameters.java renamed to docs/src/test/java/com/example/restassured/QueryParameters.java

@@ -21,32 +21,21 @@
 
 import static org.hamcrest.CoreMatchers.is;
 import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
-import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
+import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
 import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document;
 
-public class RequestParameters {
+public class QueryParameters {
 
 	private RequestSpecification spec;
 
 	public void getQueryStringSnippet() {
-		// tag::request-parameters-query-string[]
-		RestAssured.given(this.spec).filter(document("users", requestParameters(// <1>
+		// tag::query-parameters[]
+		RestAssured.given(this.spec).filter(document("users", queryParameters(// <1>
 				parameterWithName("page").description("The page to retrieve"), // <2>
 				parameterWithName("per_page").description("Entries per page")))) // <3>
 				.when().get("/users?page=2&per_page=100") // <4>
 				.then().assertThat().statusCode(is(200));
-		// end::request-parameters-query-string[]
-	}
-
-	public void postFormDataSnippet() {
-		// tag::request-parameters-form-data[]
-		RestAssured.given(this.spec)
-				.filter(document("create-user",
-						requestParameters(parameterWithName("username").description("The user's username"))))
-				.formParam("username", "Tester") // <1>
-				.when().post("/users") // <2>
-				.then().assertThat().statusCode(is(200));
-		// end::request-parameters-form-data[]
+		// end::query-parameters[]
 	}
 
 }

Diff for: docs/src/test/java/com/example/webtestclient/RequestParameters.java renamed to docs/src/test/java/com/example/webtestclient/FormParameters.java

@@ -21,37 +21,26 @@
 import org.springframework.util.MultiValueMap;
 import org.springframework.web.reactive.function.BodyInserters;
 
+import static org.springframework.restdocs.request.RequestDocumentation.formParameters;
 import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
-import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
 import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;
 
-public class RequestParameters {
+public class FormParameters {
 
 	// @formatter:off
 
 	private WebTestClient webTestClient;
 
-	public void getQueryStringSnippet() {
-		// tag::request-parameters-query-string[]
-		this.webTestClient.get().uri("/users?page=2&per_page=100") // <1>
-			.exchange().expectStatus().isOk().expectBody()
-			.consumeWith(document("users", requestParameters(// <2>
-					parameterWithName("page").description("The page to retrieve"), // <3>
-					parameterWithName("per_page").description("Entries per page") // <4>
-			)));
-		// end::request-parameters-query-string[]
-	}
-
 	public void postFormDataSnippet() {
-		// tag::request-parameters-form-data[]
+		// tag::form-parameters[]
 		MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
 		formData.add("username", "Tester");
 		this.webTestClient.post().uri("/users").body(BodyInserters.fromFormData(formData)) // <1>
-			.exchange().expectStatus().isCreated().expectBody()
-			.consumeWith(document("create-user", requestParameters(
-				parameterWithName("username").description("The user's username")
-		)));
-		// end::request-parameters-form-data[]
+				.exchange().expectStatus().isCreated().expectBody()
+				.consumeWith(document("create-user", formParameters(// <2>
+						parameterWithName("username").description("The user's username") // <3>
+				)));
+		// end::form-parameters[]
 	}
 
 }

Diff for: docs/src/test/java/com/example/webtestclient/QueryParameters.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2014-2022 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.webtestclient;
+
+import org.springframework.test.web.reactive.server.WebTestClient;
+
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
+import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;
+
+public class QueryParameters {
+
+	// @formatter:off
+
+	private WebTestClient webTestClient;
+
+	public void getQueryStringSnippet() {
+		// tag::query-parameters[]
+		this.webTestClient.get().uri("/users?page=2&per_page=100") // <1>
+			.exchange().expectStatus().isOk().expectBody()
+			.consumeWith(document("users", queryParameters(// <2>
+					parameterWithName("page").description("The page to retrieve"), // <3>
+					parameterWithName("per_page").description("Entries per page") // <4>
+			)));
+		// end::query-parameters[]
+	}
+
+}