Previously, when additional snippets were added to a
RestDocumentationResultHandler, those snippets would then be called
for every subsequent call to handle(MvcResult). This is problematic as
the snippets and their configuration are specific to a particular
MvcResult that is being documented.
This commit updates RestDocumentationResultHandler so that it clears
its additional snippets each time handle(MvcResult) is called.
Closes gh-243
Previously, it was necessary to document every payload field, link,
path parameter, or request. If an item was not documented a failure
would occur. This has proven to be too restrictive for some use cases,
for example splitting up the documentation of a payload’s fields. While
it was possible to use a preprocessor to modify the operation prior to
documentation to remove the items that should not be documented, this
was more difficult than it needed to be.
This commit adds support for marking a descriptor as ignored. Ignored
descriptors count when checking that everything has been documented but
do not actually appear in the generated documentation.
Closes gh-143
Previously, if a request had no content and it was a POST or a PUT
request, the curl request snippet would use the request's parameters
as application/x-www-form-urlencoded data sent using the -d option.
This resulted in the wrong snippet being produced if those parameters
had actually come from the request's query string.
This commit enhances CurlRequestSnippet so that, when it's using the
request's parameter's to create its content, it only includes
parameters that are not specified in the query string. With these
changes in place, this MockMvc request:
post("/?foo=bar").param("foo", "bar").param("a", "alpha")
Will produce a curl snippet with the following command:
$ curl 'http://localhost:8080/?foo=bar' -i -X POST -d 'a=alpha'
foo=bar only appears in the command's query string, despite also
being a general request parameter, and a=alpha only appears in the
request's data.
Closes gh-139
Previously, the Host header was treated specially in the HTTP request
snippet. If no Host header was specified, one would always be added
prior to producing the snippet. This ensured that the snippet was
valid (an HTTP 1.1 request must include a Host header), but came at
the cost of some confusion about why a preprocessor could not remove
it.
This commit updates the special treatment of the Host header so that
it's now performed in a central location so that all of the snippets
can benefit from a Host header being added if one isn't provided.
The handling of the Content-Length header has also been reworked so
that it's performed in the same location. The curl request snippet
has been updated so that it doesn't include setting the Host header
on the command line; it's unnecessary as curl will automatically
include a Host header in the request. The documentation of the
Host header's special treatment (made in 2fc0420) that noted that it
was unaffected by preprocessing has been reverted.
Closes gh-134
Previously, some MockMvc-specific logic would add a Content-Length
header to every request that had content. This led to the curl request
snippet containing a -H option for the Content-Length header. This is
unnecessary as curl will automatically generate a Content-Length
header based on the data that's being sent to the server. A secondary
problem was the inconsistent automatic addition of a Content-Length
header; the header was not automatically added to responses.
This commit remove the MockMvc-specific logic in favour of some new
logic in the core project to automatically add a Content-Length header
to both requests and responses. The curl request snippet has been
updated to supress the header in favour of curl's automatic
generation.
Closes gh-111
This commit configures Checkstyle and updates the build to comply with
that configuration. The Eclipse JDT metadata has also been updated
so that the output of Eclipse’s code formatting and clean-up is
compliant with Checkstyle.
The use of the latest version (6.10.1) of Checkstyle has required an
upgrade to Gradle 2.7. Gradle hardcode’s the name of the Checkstyle’s
main class which has changed between version 5 (Gradle’s default) and
version 6.
Closes gh-119
Following the reworking of the API, it was no longer possible to
apply preprocessing to every test and to still customize the snippets
used by that test.
This commit adds a new snippets() method to
RestDocumentationResultHandler that allows additional snippets to be
configured once the result handler has been created. The documentation
has been updated to describe how to apply preprocessing to every
test and Spring HATEOAS sample has been updated to illustrate the
approach.
Closes gh-88
Windows uses \r\n for line endings whereas Unix-like platforms us
\n. This causes the content length of a pretty-printed response to
be longer on Windows.
This commit splits Spring REST Docs into two projects –
spring-restdocs-core and spring-restdocs-mockmvc.
spring-restdocs-core contains the vast majority of the code but does not
depend on a specific test framework other than JUnit. The use of a
Spring Test TestExecutionListener has been replaced with a JUnit test
rule. The rule is declared once per test class and configured with
the output directory to which the generated snippets should be written.
This simplifies the implementation as thread local storage is no longer
required to transfer information about the test that’s running into
Spring REST Docs. Instead, this transfer is now handled by the new test
rule. It has also simplified the configuration as it’s no longer
necessary for users to provide a system property that configures the
output directory.
spring-restdocs-mockmvc contains code that’s specific to using Spring
REST Docs with Spring MVC Test’s MockMvc. This is currently the only
testing framework that’s supported, but it paves the way for adding
support for additional frameworks. REST Assured is one that users seem
particularly interested in (see gh-80 and gh-102).
Closes gh-107
