Previously a TemplatedSnippet could only write snippets with the
same name as its template. This meant that the same template could
not be used to produce multiple snippets with different names.
This commit separates the snippet name from the template name, thereby
allowing the snippet name to vary while the template name remains the
same. For backwards compatibility, the default behaviour is for the
template name and snippet name to remain the same. The new overloaded
constructor can be used when the names need to differ.
Closes gh-320
Previously, a LinkDescriptor had to be created with both a rel and a
description. If a description was not provided a failure would occur.
This commit relaxes the above-described restriction by allowing a
link's title to be used as its default description. If a descriptor
has a description, it will always be used irrespective of whether or
not the link has a title. If the descriptor does not have a
description and the link does have a title, the link's title will be
used. If the descriptor does not have a description and the link does
not have a title a failure will occur.
Closes gh-105
This commit polishes the HTTPie request snippet contribution made in
b26d8c0. It makes the following significant changes:
- Applies project’s coding conventions for formatting and the like
- Moves to a composition-based approach for sharing functionality
between the curl and HTTPie snippets by replacing AbstractCliSnippet
with CliOperationRequest.
- Introduces a single package for CLI command snippets, thereby allowing
more code to be package-private.
See gh-207
Previously, custom snippet templates were loaded from
org/springframework/restdocs/templates and the default templates were
loaded from org/springframework/restdocs/templates/{$formatId}.
Without relying on the ordering of the classpath, this made it
impossible to provide a custom template for a specific format.
This commit updates the locations that are checked for snippet
templates. The following locations are now checked in order:
1. org/springframework/restdocs/templates/${formatId}/${name}.snippet
2. org/springframework/restdocs/templates/${name}.snippet
3. org/springframework/restdocs/templates/${formatId}/default-${name}.snippet
The second location is provided largely for backwards compatibility
with 1.0. Users are expected to use the first location to provide
any custom templates, with Spring REST Docs provided templates for
all of the built-in snippets in the third location.
Closes gh-196
Closes gh-197
This commit introduces support for generating snippets formatted
using Markdown. Asciidoctor remains the default.
A new SnippetFormat abstraction has been introduced with Asciidoctor
and Markdown implementations provided out of the box.
Markdown-formatted templates are also provided for all of the default
snippets.
Please refer to the updated reference documentation for further
details.
Closes gh-150
Closes gh-19
Previously, the description of a link, parameter, or field had to be a
String. Given the use of Mustache templates, this was unnecessarily
restrictive. It prevented the use of a richer object, the components of
which could then be accessed in a template.
This commit changes the description of links, parameters, and fields to
be an Object, thereby allowing richer objects to be used. The default
template will call toString on the description during rendering. Custom
templates can be used to make more sophisticated use of the description.
To ensure that the description is consistent across all descriptor
types, it has been moved up onto the AbstractDescriptor superclass.
Closes gh-123
The commit opens up all of the default snippets so that it's easier
to extend them and modify their behaviour. All of the built-in
snippets are now public with protected constructors. Also, where
appropriate the models used by the snippets have been made more
fine-grained.
Closes gh-73
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
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 link extraction abstraction was inadequate as it made
assumptions about the format of the links that did not apply to all
media types. For example, it was suited to the links returned in a
application/hal+json response, but was not suited to the Atom-style
links often found in application/json responses.
This commit improves the abstraction so that the extracted links are
decoupled from the format of the response. In addition to the existing
support for extracting HAL links a new extractor for Atom-style links
has been introduced. Both extractors are now available via static
methods on the new LinkExtractors class. The sample applications have
been updated accordingly.
Closes#6
