This version is still in development and is not considered stable yet. For the latest stable version, please use Spring REST Docs 4.0.0!

Form Parameters

You can document a request’s form parameters by using formParameters. The following examples show how to do so:

MockMvc
WebTestClient

import org.junit.jupiter.api.Test;

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;

class FormParameters {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		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)
			)));
	}

}

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`.

import org.junit.jupiter.api.Test;

import org.springframework.test.web.reactive.server.WebTestClient;
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.webtestclient.WebTestClientRestDocumentation.document;

public class FormParameters {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		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", formParameters((2)
					parameterWithName("username").description("The user's username") (3)
			)));
	}

}

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`.

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 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 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 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.