Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Provide obvious support for documenting all request parameters

Browse Source 
Previously, the snippet for documenting a request’s parameters was
referred to as the query parameters snippet. This was misleading as the
snippet would actually document anything in the request’s parameters
map, not just parameters from the request’s query string.

This commit renames the snippet and the associated templates, etc so
that it is now known as the request parameters snippet. This provides
a more accurate reflection of it being able to document all of a
request’s parameters, not just those from its query string.

Closes gh-104
This commit is contained in:
Andy Wilkinson
2015-08-18 10:07:39 +01:00
parent dfd65f9f10
commit d3e1a0d1b6
11 changed files with 151 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/src/docs/asciidoc/documenting-your-api.adoc
View File

@@ -174,27 +174,37 @@ include::{examples-dir}/com/example/Payload.java[tags=explicit-type]
[[documenting-your-api-query-parameters]]
=== Query parameters
[[documenting-your-api-request-parameters]]
=== Request parameters
A request's query parameters can be documented using `queryParameters`
A request's parameters can be documented using `requestParameters`. Request parameters
can be included in a `GET` requests query string:
[source,java,indent=0]
----
include::{examples-dir}/com/example/QueryParameters.java[tags=query-parameters]
include::{examples-dir}/com/example/RequestParameters.java[tags=request-parameters-query-string]
----
<1> Produce a snippet describing the request's query parameters. Uses the static
`queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
<2> Document a parameter named `page`. Uses the static `parameterWithName` method on
<1> Perform a `GET` request with two parameters in the query string.
<2> Produce a snippet describing the request's parameters. Uses the static
`requestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
<3> Document a parameter named `page`. Uses the static `parameterWithName` method on
`org.springframework.restdocs.request.RequestDocumentation`.
<3> Document a parameter named `per_page`.
<4> Document a parameter named `per_page`.
The result is a snippet named `query-parameters.adoc` that contains a table describing
the query parameters that are supported by the resource.
They can also be included as form data in the body of a POST request:
When documenting query parameters, the test will fail if an undocumented query parameter
is used in the request. Similarly, the test will also fail if a documented query parameter
is not found in the request.
[source,java,indent=0]
----
include::{examples-dir}/com/example/RequestParameters.java[tags=request-parameters-form-data]
----
<1> Perform a `POST` request with a single parameter.
In both cases, the result is a snippet named `request-parameters.adoc` that contains a
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.

29
docs/src/test/java/com/example/QueryParameters.java → docs/src/test/java/com/example/RequestParameters.java
View File

@@ -18,25 +18,36 @@ package com.example;
import static org.springframework.restdocs.RestDocumentation.document;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.RestDocumentationRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.springframework.test.web.servlet.MockMvc;
public class QueryParameters {
public class RequestParameters {
private MockMvc mockMvc;
public void queryParametersSnippet() throws Exception {
// tag::query-parameters[]
this.mockMvc.perform(get("/users?page=2&per_page=100"))
public void getQueryStringSnippet() throws Exception {
// tag::request-parameters-query-string[]
this.mockMvc.perform(get("/users?page=2&per_page=100")) // <1>
.andExpect(status().isOk())
.andDo(document("users", queryParameters( // <1>
parameterWithName("page").description("The page to retrieve"), // <2>
parameterWithName("per_page").description("Entries per page") // <3>
.andDo(document("users", requestParameters( // <2>
parameterWithName("page").description("The page to retrieve"), // <3>
parameterWithName("per_page").description("Entries per page") // <4>
)));
// end::query-parameters[]
// 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[]
}
}