Free tools Windows power users keep installed
One-click scans. No signup required.
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use Spring REST Docs’ formParameters(...) in the test that sends the form. It generates a form-parameters.adoc snippet describing the form fields, and strict mode checks that the request and its documented parameters agree.
What formParameters documents
formParameters describes fields in a request’s form body. It does not document values in the URL query string: use queryParameters for those instead. The generated form-parameters.adoc snippet contains a table of the form parameters supported by the resource. See Spring’s form-parameter reference.
Keep the test’s request construction aligned with the actual location of each value. A field sent in the form body belongs in the form-parameter snippet; a value sent in the query string belongs in the query-parameter snippet. For path values, use pathParameters.
Document form fields in a test
Add descriptors to the request test that performs the operation. Each descriptor names a form field and explains its meaning to API consumers.
#1 Best Overall
MockMvc
For a MockMvc test, send the form value, assert the expected response, and pass the form snippet to document. The official example imports formParameters and parameterWithName from org.springframework.restdocs.request.RequestDocumentation.
formParameters(
parameterWithName("username").description("The user's username")
)Include that snippet in the operation’s documentation call after performing and asserting the request. The request and descriptors should represent the same form contract.
Rank #2
WebTestClient
For WebTestClient, put the form values in a MultiValueMap<String, String>, send them with BodyInserters.fromFormData(formData), assert the response, and document the operation using the same descriptor pattern. Spring documents both MockMvc and WebTestClient; use the client already used in the project.
Choose strict or relaxed coverage
Strict: document the complete form contract
Use formParameters(...) when the test is meant to cover the complete set of form fields. Spring REST Docs fails the snippet invocation if the request contains a form field without a descriptor. It also fails when a documented, non-optional field is missing from the request. These checks help expose drift between the test request and the published contract.
Relaxed: document a subset
Use relaxedFormParameters(...) when the snippet should describe only selected fields and other request fields should not cause a failure. Relaxed mode does not remove the presence requirement for a documented field: a descriptor for a non-optional field still requires that field in the request. See the RequestDocumentation API.
Control whether fields appear in the snippet
- Document a visible field: use
parameterWithName("fieldName").description(...)and describe its meaning. - Document a field that may be absent: mark its descriptor optional so the request does not have to include it.
- Exclude a field from the output: mark its descriptor ignored. The descriptor prevents a strict mismatch for that request field while omitting it from the generated snippet.
The API provides parameterWithName(String) and form-parameter overloads that accept descriptors as varargs or lists; overloads can also accept rendering attributes.
Keep query, form, and path values distinct
Use the request’s actual parameter location to choose the documentation snippet. formParameters covers fields in the form body, queryParameters covers query-string values, and pathParameters covers values in the URL path. Spring’s query-parameter reference puts query values in the URL and cautions against request-builder param/params when the source would be ambiguous. The path-parameter reference covers path values.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
