Previously, users that wanted to document a request field’s constraints
had to roll their own solution. This commit introduces a new API that
makes it easier to document constraints. Support is provided for
discovering Bean Validation constraints and resolving descriptions for
them. The constraint descriptions can then be used as required. For
example, they can included in a field’s description or in an additional
constraints attribute that’s included in an additional table column via
the use of a custom snippet template.
Closes gh-42
The ordering of parameters in the path is important so, without seeing
the path and the order in which the parameters appear, documentation for
the individual parameters is of limited use.
This commit enhances the path parameters snippet to include the
request’s path, minus any query string, in the snippet. By default,
the path is rendered as the title of the parameters table. As with
other snippets, this can be customized by providing a custom template
for the snippet.
Closes gh-103
Previously, the snippet for documenting a request’s parameters was
referred to as the query parameters snippet. This was misleading as the
snippet would actually document anything in the request’s parameters
map, not just parameters from the request’s query string.
This commit renames the snippet and the associated templates, etc so
that it is now known as the request parameters snippet. This provides
a more accurate reflection of it being able to document all of a
request’s parameters, not just those from its query string.
Closes gh-104
This commit updates the API to improve its extensibility and
readability.
SnippetWritingResultHandler has been replaced with a more general
purpose Snippet interface. Snippets are now provided to the main
document method using varargs rather than the various with… methods
that were previously used. As a result a custom Snippet implementation
can now be used in exactly the same way as any of the built-in
snippets:
this.mockMvc.perform(get("/"))
.andExpect(status().isOk())
.andDo(document("index-example",
links(
linkWithRel("notes").description("…"),
linkWithRel("tags").description("…")),
responseFields(
fieldWithPath("_links").description("…")),
yourCustomSnippet()));
Control of the snippets that are generated by default is now available
via RestDocumentationConfigurer:
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(documentationConfiguration().snippets()
.withDefaults(curlRequest(), yourCustomSnippet()))
.build();
See gh-73
Previously, SnippetWritingResultHandler hard-coded its own logic for
creating the Writer that used to write its snippet. This made it
impossible to take complete control over the output location, filename
suffix, etc.
This commit introduces a new interface, WriterResolver, and a default
implementation, StandardWriterResolver. It provides the same
functionality as before, but SnippetWritingResultHandler now
retrieves an instance of WriterResolver from the request's attributes.
This allows users to provide their own WriterResolver implementation.
Closes gh-100
This commit adds support for associating custom attributes with the
generation of a particular snippet. The attributes are included in
the model during snippet rendering allowing them to be referenced from
a custom snippet template. Among other things, this makes it possible
to provide a configurable title for snippets that produce a code
block.
Closes gh-77
This commit adds support for associating custom attributes with field,
link, and query parameter descriptors. These attributes are then
included in the model during snippet rendering. Coupled with a custom
snippet template, this enables the inclusion of extra column(s) in the
generated tables.
Closes gh-70
This commit introduces a new TemplateEngine abstraction that is used
to produce the documentation snippets. A default JMustache-based
implementation is provided. JMustache has been repackaged and embedded
to prevent unwanted conflicts and side-effects.
By default, snippet templates are loaded from the classpath in the
org.springframework.restdocs.templates package. Default snippet
templates are provided for all of the snippets that can be generated.
Each of these templates is named after the snippet that it will
produce – the snippet {name}.adoc is produced by the snippet template
default-{name}.snippet. A snippet named {name}.snippet, if present,
will be used in preference to the default snippet, thereby allowing
the default snippets to be overriden.
Previously, request parameters for a POST were form encoded into the
body, irrespective of the request’s type. This was incorrect for a
multipart request where each request parameter should be included in a
separate request part.
This commit updates HttpDocumentation to treat request parameters
differently when dealing with a multipart request. In such cases each
request parameter is now included in the body of the request in a
separate request part.
Fixes gh-94
Previously, request parameters would be provided via -d. This is
incorrect for a multipart request that is also using -F. This commit
updates the generation of the curl request snippet to use -F for request
parameters when the request is a multipart request.
Closes gh-93
HTTP 1.1 requires a Host: header in all requests. This commit updates
the HTTP request snippet to ensure that such a header is always
present.
Closes gh-85
Previously, if an optional field was being documented and that field
was not present in the payload a failure would occur with the message
"The payload does not contain a field with the path 'the.field.path'".
This isn't very helpful as it doesn't explain why the field was being
looked for (to resolve its type).
This commit improves the diagnostics to improve the message to explain
that a field's type could not be determined as it didn't exist in the
payload and to suggest the use of FieldDescriptor.type(FieldType) to
provide a type.
Closes gh-83
- 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
