Previously both samples supported Maven and Gradle. Due to the different
default locations between the two build systems, the Gradle-based sample
was configured to use Maven’s default location for its .adoc files.
The samples have now been updated so that one sample uses Maven and the
other uses Gradle. However, when this change was made, the customization
of the Gradle-based sample’s .adoc file location wasn’t removed.
This commit updates the Gradle-based sample to use the default location,
src/docs/asciidoc, for its .adoc source files.
Closes gh-145
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
For an HTTP 1.1 request to be valid it must contain a Host header. To
ensure that the HTTP request snippet is a valid HTTP 1.1 request a
Host header will always be included. If one is not present in the
request that’s being documented, the snippet will generate one
automatically. A side-effect of this is that a preprocessor that removes
the Host header will have no effect on the HTTP request snippet. This
commit updates the documentation to describe this behaviour.
Closes gh-134
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, to see an example of the documentation that can be
produced by Spring REST Docs, users had to clone the repository and
build one of the samples.
This commit makes it easier to see what Spring REST Docs can do by
updating the docs zip that's automatically published to docs.spring.io
to include both the API Guide and the Getting Started Guide from the
RESTful notes sample.
Closes gh-112
- Correct the location of the Git repository
- Correct the location of the sample within the repository
- Update the build instructions for the Data REST sample to use Maven
- Move the table of contents to the left
- Add section links
Closes gh-113
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
