Provide separate snippets for documenting query parameters and form parameters
wilkinsona opened this issue · comments
When REST Docs was first implemented, it only supported Spring Framework's MockMvc which is heavily Servlet based. This led to a snippet for the Servlet concept of request parameters being provided. With hindsight, this was a mistake. Request parameters are a server-side construct that provides access to parameters from the request URI's query string or from posted form data. From a client's perspective, the parameters have two separate sources and, as such, they should be documented separately in client-facing documentation. Rather than providing a snippet for request parameters, REST Docs should provide separate snippets for query parameters and form parameters.
To provide a smooth migration path from REST Docs 2.0.x to 3.0.x, the intention is to treat this as a bug. Support for documenting request parameters will be deprecated in 2.0.x and, at the same time, support for documenting query parameters and form parameters will be introduced. Then, in 3.0.x, the deprecated support for documenting request parameters will be removed.
Making these changes in a completely backwards-compatible way is too involved and, therefore, too risky for 2.0.x. Instead, these changes will only be made in 3.0 with users having to adapt to the breaking change on upgrade.