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, 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
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
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
Following the reworking of the API, it was no longer possible to
apply preprocessing to every test and to still customize the snippets
used by that test.
This commit adds a new snippets() method to
RestDocumentationResultHandler that allows additional snippets to be
configured once the result handler has been created. The documentation
has been updated to describe how to apply preprocessing to every
test and Spring HATEOAS sample has been updated to illustrate the
approach.
Closes gh-88
This commit splits Spring REST Docs into two projects –
spring-restdocs-core and spring-restdocs-mockmvc.
spring-restdocs-core contains the vast majority of the code but does not
depend on a specific test framework other than JUnit. The use of a
Spring Test TestExecutionListener has been replaced with a JUnit test
rule. The rule is declared once per test class and configured with
the output directory to which the generated snippets should be written.
This simplifies the implementation as thread local storage is no longer
required to transfer information about the test that’s running into
Spring REST Docs. Instead, this transfer is now handled by the new test
rule. It has also simplified the configuration as it’s no longer
necessary for users to provide a system property that configures the
output directory.
spring-restdocs-mockmvc contains code that’s specific to using Spring
REST Docs with Spring MVC Test’s MockMvc. This is currently the only
testing framework that’s supported, but it paves the way for adding
support for additional frameworks. REST Assured is one that users seem
particularly interested in (see gh-80 and gh-102).
Closes gh-107
Prior to this commit it was not possible to modify a request prior to
it being documented, only a response. This commit builds on the new
Operation abstraction to simplify the existing response modification
support and to add support for request modification.
Closes gh-84
Prior to this commit, MockMvc-classes were used throughout Spring REST
Docs. For example, each Snippet was called with an MvcResult. This
has proven problematic for a few reasons:
1. The MockMvc APIs aren't very amenable to modifying a request or
response before it's documented. This caused the existing support
for response modification to rely on CGLib proxies and method
interceptors. A similary complex solution for request modifiction
would also have been necessary.
2. Things are harder to reason about than they need to be as the
MockHttpServletRequest and MockHttpServletResponse classes
expose more than is required when generating API documentation.
3. Supporting other test frameworks, such as Rest Assured, is hard
This commit introduces a new Operation abstract that encapsulates
all of the information required to document the request that was sent
and the response that was received when performing an operation on a
RESTful service. The new abstraction uses types from Spring's Web
support, such as HttpHeaders, RequestMethod, and MediaType, but does
not rely on MockMvc.
Closes gh-108
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.
