Previously, both the curl and HTTP request snippets would ignore
a parameter with no value, for example from the query string of the
url http://localhost:8080/foo?bar.
This commit updates both snippets so that such parameters are
included in the generated snippet, including a multi-part request
that is uploading form data and a field in the form has no value.
Additions have been made to the tests for both snippets.
While the request parameters snippet correctly handled parameters with
no value, there was no test verifying that this was the case. One
has been added in this commit.
Closes gh-200
Previously, PrettyPrintingContentModifier would convert the byte[]
content into a String and then back into a byte[]. It did so without
consideration for the content’s character set. As a result, it could
fail to preserve the correct character encoding.
This commit updates PrettyPrintingContentModifier to avoid converting
the content into a String and back into a byte[] and to work entirely
with byte arrays instead. Removing the intermediate String from the
process removes the possibility of the content becoming corrupted.
Closes gh-202
Documenting an XML attribute in the XML payload leads to a
NullPointerException since no parent nodes exists for an XML
attribute. Rather than always trying to remove a node from its parent,
this commit changes the logic to apply special treament to nodes that
are attributes and remove the attribute from its owning element
instead.
Closes gh-167
Previously, when the XML pretty printer attempted to pretty print
the content of a request or response it would output an error to
System.err if the content was not valid XML. While, benign, this
output was distracting.
This commit updates the XML pretty printer to suppress its output to
System.err by configuring it with an ErrorHandler and an ErrorListener
that swallow any errors of which they are notified.
Closes gh-153
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
The main changes are:
- Update javadoc to align with changes made in 5a01016
- Update documentation with details of the new support for documenting
HTTP headers
- Add tests to verify that HTTP headers are matched case-insensitively
Closes gh-71
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
Using UTF-8 in the source can be problematic on platforms that are
not configured to use UTF-8 by default. This commit replaces a number
of strings with UTF-8 characters in them with an equivalent ASCII
string that uses unicode character escapes.
This commit builds on the changes made in the previous commit to
make wider use of the new getContentAsString methods on
OperationRequest and OperationResponse. It also adds such a method to
OperationRequestPart. Any code that previously got the content as a
byte array and then created a String has been updated to either use
getContentAsString or to use the charset from the Content-Type header
when creating a String.
See gh-126
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
Previously, only dot notation JSON field paths were supported. Using
dot notation, each key is separated by a '.'. This makes it impossible
to reference a field where the key itself contains a dot.
This commit adds basic bracket notation support to JsonFieldPath.
With this commit, existing functionality remains as is, but users can
now use a basic form of JsonPath bracket notation. This enables the
use of Json keys with embedded dots. i.e. something like :
{
"a.b" : "one"
}
.andDo(document("example",responseFields(fieldWithPath("['a.b']")…
Closes gh-132
Previously, when a request was made that used basic auth, the curl
snippet would configure the authentication header with the
Base64-encoded header. This commit updates the snippet to use the
more human-friendly -u option to provide the username and password
in place of the authentication header.
Closes gh-122
Previously, the description of a link, parameter, or field had to be a
String. Given the use of Mustache templates, this was unnecessarily
restrictive. It prevented the use of a richer object, the components of
which could then be accessed in a template.
This commit changes the description of links, parameters, and fields to
be an Object, thereby allowing richer objects to be used. The default
template will call toString on the description during rendering. Custom
templates can be used to make more sophisticated use of the description.
To ensure that the description is consistent across all descriptor
types, it has been moved up onto the AbstractDescriptor superclass.
Closes gh-123
This commit adds support for three new placeholders that can be used
when specifying the name of an operation: {ClassName}, {class-name},
and {class_name}. This allows the operation name to be configured once
in an abstract superclass and reused across multiple test classes.
Closes gh-116
Previously, ContentModifier and ContentModifyingOperationPreprocessor
were package-private. This meant that anyone wishing to perform content
modification during preprocessing had to reimplement much of the
existing content modifying preprocessor, that than just having to
implement ContentModifier.
This commits make both ContentModifier and
ContentModifyingOperationPreprocessor public so that all custom
content modification is now a matter of implementing a custom
ContentModifier and creating an instance of
ContentModifyingOperationPreprocessor.
Closes gh-121
Previously, RestDocumentationContextPlaceholderResolver could be
subclassed, but it didn’t provide access to its state (the
RestDocumentationContext).
This commit opens up RestDocumentationContextPlaceholderResolver by
adding a getter method for its RestDocumentationContext. It also makes
the kebab-base and snake_case conversion methods protected (rather than
private) so that they can be used by subclasses.
See gh-116
This commit improves the extensibility of the various descriptor
classes. The following changes have been made:
- Constructors have been made protected to allow them to be called by
subclasses in a different package
- Model creation has been moved to the relevant snippet class. This
improves the separation of concerns as a descriptor should not be
aware of template-based rendering and the need for a model. The
method is protected to allow it to be overridden by a custom subclass
that uses a custom descriptor subclass.
- Methods that should not be overridden have been made final.
See gh-73
This commit updates each of the built-in snippet implementations to
provide protected getter methods for their fields. This allows
subclasses to access and work with the snippet’s state.
See gh-73
The commit opens up all of the default snippets so that it's easier
to extend them and modify their behaviour. All of the built-in
snippets are now public with protected constructors. Also, where
appropriate the models used by the snippets have been made more
fine-grained.
Closes gh-73
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
