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
This commit introduces support for documenting the fields in a request
and response, modelled on the existing support for documenting links.
A test with field documentation enabled will fail if a documented
field is missing from the request or response, or if a field present
in the request or response has not been documented.
See gh-24
Closes gh-25
Previously, when producing the curl snippet for a POST request, the
request's parameter map was ignored. This commit updates the snippet
generation to look at the parameter map and POST it to the server
as application/x-www-form-urlencoded data using -d
Closes gh-38
Previously, only the request's query string was considered when
creating the curl command's request URI. This meant that query
parameters configured via request.addParameter where not included in
the URI.
This commit enhances CurlRequestDocumentationAction so that, in the
absence of a query string, it will use a GET request's parameters to
produce the query string include in the curl command's URI.
Closes gh-26
Closes gh-30
This commit adds an API to DocumentationWriter for producing
documentation snippets containing tables. The API is intended to be
fairly simple such that it can be implemented for a variety of
different output formats, and not just for Asciidoctor (the only
currently supported format).
Closes gh-34
The MVC test framework provides an alwaysDo method which allows the
configuration of a result handler to be that will be invoked for every
call to perform. Previously, this method could not be used for
producing documentation snippets as the snippets would overwrite each
other.
This commit adds support for writing snippets to a parameterized
output directory. Two parameters are supported: method name and step.
Method name is the name of the currently executing test method. Step
is a count of the number of calls to MockMvc.perform that have been
made in that method.
Closes gh-14
Previously an HTTP request to localhost on port 80 or an HTTPS request
to localhost on 443 would generate curl request snippets with the
uris http://localhost:80 and https://localhost:443 respectively. While
specifying the port does no harm, it is unnecessary.
This commit updates CurlDocumentation so that the uri in the request
snippet does not include the port when the port is the default for the
uri’s scheme.
Closes gh-17
