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
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
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.
