- Make inner classes static where possible
- Declare classes as final where appropriate
- Use try-with-resources
- Improve readability by breaking up some large methods
- Do not throw Throwable where possible
Previously, if a link was documented then it had to be present in the
response payload for the test to pass. This was unnecessarily
restrictive and caused problems when a link was omitted due to the
application's current state.
This commit allows a link to be declared as optional. If a link is
optional then the test will pass irrespective of the link's presence
in the response.
See gh-74
764daf7 added support for documenting fields in payloads that contain
arrays, but the array had to be nested within a map. This commit builds
on that support to allow fields in an array payload to be
documented. The fields in the payload:
[
{
"a": {
"b": 5
}
},
{
"a": {
"c": "charlie"
}
}
]
Can be documented using:
[]a.b
[]a.c
[]a
A dot separator can, optionally, be used between the [] and the map key:
[].a.b
[].a.c
[].a
Closes gh-69
Previously, snippets were written to disk using the JVM’s default
encoding. While this could be controlled by the file.encoding system
property it was not ideal as, if the proper was not always set, it could
lead to platform-dependent output being generated. Furthermore,
Asciidoctor uses UTF-8 encoding by default so there was a risk of the
snippets being generated in a different encoding to the encoding
expected by Asciidoctor.
This commit updates the configuration so that, by default, snippets are
encoded as UTF-8. The RestDocumentationConfigurer API has been enhanced
to allow this default to be configured as part of building the
MockMvc instance. This enhancement as brought with it a more fluent
configuration API that separates configuration that is related to URIs
from configuration that is related to snippets.
Closes gh-67
The main project supports Java 7 or later, but, prior to this commit,
the Spring HATEOAS sample required Java 8. This commit updates updates
the Spring HATEOAS sample to make it compatible with Java 7 and
updates the build configuration of both samples to specify Java 7.
Closes gh-51
This commit introduces a new ResponsePostProcessor,
PatternReplacingResponsePostProcessor, that modifies the content of the
response by replacing occurrences of a regular expression with a
configurable replacement. The existing LinkMaskingResponsePostProcessor,
which was already performing pattern replacement, has been updated to
subclass PatternReplacingResponsePostProcessor.
Closes gh-65
Previously, no special consideration was given to PUT requests. This
meant that curl and HTTP request snippets would not include the
request’s parameters/query string and that HTTP request snippets would
not set the content type to application/x-www-form-urlencoded.
This commit addresses these limitations by updating both
HttpDocumentation and CurlDocumentation to treat PUT requests in the
same way as POST requests.
Closes gh-62
This commit adds support for post-processing a response before it is
documented. Post-processors are provided to pretty-print JSON and XML
responses, remove headers from the response, and mask the hrefs of
Atom- and HAL-formatted links in JSON responses.
Response post-processing is configured prior to configuring the
documentation. For example,
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(modifyResponseTo(prettyPrintContent(), removeHeaders("a"),
maskLinks()).andDocument("post-processed"));
Closes gh-61
Closes gh-31
Closes gh-54
This commit adds support for documenting a request's query parameters.
For example:
mockMvc.perform(
get("/issues").param("page", "2").param("limit", "20"))
.andDo(documentQueryParameters("list-issues",
parameterWithName("page")
.description("Page number to return"),
parameterWithName("limit")
.description("Maximum page size")));
Closes gh-39
Previously the path used to document a field had to be dot-separated,
with each segment of the path being used as a key in a map. This made
it impossible to document fields in a payload within an array.
This commit adds support for using [] in a field’s path to represent an
array. For example, the fields in following JSON payload:
{
"id": 67,
“date”: "2015-01-20",
"assets": [
{
"id":356,
"name": "sample"
}
]
}
Can now be documented using the following paths:
- id
- date
- assets[].id
- assets[].name
Closes gh-60
Enhance buildSamples such that, once a sample has been built, it looks
at the generated HTML files and checks that they do not contain any
output that's indicative of a malformed include in a source .adoc
file.
This additional verification found another malformed include which
this commit corrects.
- If the request has no Content-Type (null or an empty string), a
null extractor is returned rather than an exception being thrown.
This is consistent with the old behaviour.
- Tests have been reworked a little bit to separate out the new normal
unit tests from the existing parameterised tests.
Closes gh-56
This commit adds the necessary configuration to build the project
on Travis CI. First, the main project is built using Java 7 then the
samples are built using Java 8.
Closes gh-58
Single quotes are generally safer to use since shells won't try to
interpolate any strings or do variable substitution inside it. This
could be refined to do a check for [&%$] inside the URI/query string
before just blindly surrounding with quotes, but this is safe as it is.
Also, don't escape POST paylods since they are quoted already – this
doesn't work correctly right now.
Closes gh-55
A context path should either be an empty String, or a String that
begins with a slash. This commit updates both CurlDocumentation and
RestDocumentationConfigurer to prepend a / to the specified context
path when required.
See gh-49
Previously, a custom host was configured by setting the request’s
remote host. This is in correct as the remote host as the client’s host.
The custom port was also being configured by setting the request’s
remote port and server port. Only the latter is required.
This commit correct the logic by setting the request’s server name and
server port when configuring a custom host and custom port respectively.
The tests have been improved by introducing the use of Spring HATEOAS’s
BasicLinkBuilder to verify that the configured request produces the
expected scheme, host and port in any generated links.
Closes gh-44
This commit improves the support for documenting the fields found
in request and response payloads. The improvements include:
- Using the term "payload" rather than "state" as the latter is
somewhat HAL-specific
- Code simplification, including the removal of the Path abstraction
- Automatically determining the type of a field based on the payload
that's being tested
- Updating the samples to use the new API
In addition to these improvements, support for documenting field
constraints has been removed as more thought is required. The
FieldDescriptor abstraction is used to describe both request and
response fields, however it's not clear that contraints apply to both
and they certainly don't apply in the same way. For the time being at
least, users who want to document a field's constraints can do so as
part of its description.
Closes gh-24
