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
This commit is contained in:
Andy Wilkinson
@@ -649,21 +649,20 @@ 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.
|
||||
@@ -671,11 +670,11 @@ Uses the static `parameterWithName` method on `org.springframework.restdocs.requ
|
||||
[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.
|
||||
@@ -683,51 +682,77 @@ Uses the static `parameterWithName` method on `org.springframework.restdocs.requ
|
||||
[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.
|
||||
|
||||
|
||||
|
||||
|
||||
40
docs/src/test/java/com/example/mockmvc/FormParameters.java
Normal file
40
docs/src/test/java/com/example/mockmvc/FormParameters.java
Normal file
@@ -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[]
|
||||
}
|
||||
|
||||
}
|
||||
@@ -20,31 +20,22 @@ import org.springframework.test.web.servlet.MockMvc;
|
||||
|
||||
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[]
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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[]
|
||||
}
|
||||
|
||||
}
|
||||
@@ -21,32 +21,21 @@ import io.restassured.specification.RequestSpecification;
|
||||
|
||||
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[]
|
||||
}
|
||||
|
||||
}
|
||||
@@ -21,37 +21,26 @@ import org.springframework.util.LinkedMultiValueMap;
|
||||
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[]
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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[]
|
||||
}
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user