Previously, to see an example of the documentation that can be
produced by Spring REST Docs, users had to clone the repository and
build one of the samples.
This commit makes it easier to see what Spring REST Docs can do by
updating the docs zip that's automatically published to docs.spring.io
to include both the API Guide and the Getting Started Guide from the
RESTful notes sample.
Closes gh-112
Previously, the generated pom files were uncustomised and relied on
Gradle’s default output. Such pom files are problematic for a couple
of reasons: they include test dependencies and they don’t include the
metadata that’s required for publishing to Maven Central.
This commit customises the generated pom files to include the required
metadata and to remove any test dependencies.
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
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
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.
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
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
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
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
This commit makes extensive changes to the structure of the code. It
introduces a number of separate packages to provide better separation
of the various areas of functionality. Alongside this change the project
has been renamed from spring-restdocs-core to spring-restdocs.
The build has been improved to provide support for building the samples
from the main build using the buildSamples task. While this change has
been made, the samples remain standalone projects so that their
configuration is not dependent on the main project’s build. Running
buildSamples will build the samples using both Maven and Gradle.
All of the main project’s classes now have javadoc and licence/copyright
headers.
Previously, the project provided a Gradle plugin and was only really
intended for use with Gradle. This had influenced a number of design
choices that have proven to be less than ideal when attempting to
use the project with Maven.
This commit backs off from a number of design decisions that worked
well with Gradle but less so with Maven. Part of this is that the
Gradle plugin is (temporarily?) no more. It's been removed in favour
of configuring things directly in build.gradle. While this slightly
increases the amount of configuration required it makes things far
more flexible.
Both samples have been updated with modified Gradle configuration and
new Maven configuration. The README has also been updated to reflect
these changes.
Previously, whenever a MockMvc perform call was made and the request
and response were to be documented, calls to documentCurlRequest and
documentCurlResponse had to be made.
This commit updates the REST documentation framework to make the
documentation of the request and response automatic. It makes use of
MockMvc’s MockMvcConfigurer that was introduced in Spring 4.1. Applying
RestDocumentationConfiguration once will cause all requests and
responses to be documented:
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(new RestDocumentationConfiguration()).build();
The path to which the requests and response documentation snippets will
be written is determined by the class and method in which the MockMvc
perform call is made and is currently of the form
shortClassName/methodName(Request|Response|RequestResponse).asciidoc
where shortClassName is the name of the documentation class without its
package. This works for both @Test methods and any non-private methods
that are called from the test method. The methods must be non-private as
a CGLib proxy is used to intercept the calls and configure the output
path.
