Previously, when a request was made that used basic auth, the curl
snippet would configure the authentication header with the
Base64-encoded header. This commit updates the snippet to use the
more human-friendly -u option to provide the username and password
in place of the authentication header.
Closes gh-122
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
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
Previously, ContentModifier and ContentModifyingOperationPreprocessor
were package-private. This meant that anyone wishing to perform content
modification during preprocessing had to reimplement much of the
existing content modifying preprocessor, that than just having to
implement ContentModifier.
This commits make both ContentModifier and
ContentModifyingOperationPreprocessor public so that all custom
content modification is now a matter of implementing a custom
ContentModifier and creating an instance of
ContentModifyingOperationPreprocessor.
Closes gh-121
Previously, RestDocumentationContextPlaceholderResolver could be
subclassed, but it didn’t provide access to its state (the
RestDocumentationContext).
This commit opens up RestDocumentationContextPlaceholderResolver by
adding a getter method for its RestDocumentationContext. It also makes
the kebab-base and snake_case conversion methods protected (rather than
private) so that they can be used by subclasses.
See gh-116
This commit improves the extensibility of the various descriptor
classes. The following changes have been made:
- Constructors have been made protected to allow them to be called by
subclasses in a different package
- Model creation has been moved to the relevant snippet class. This
improves the separation of concerns as a descriptor should not be
aware of template-based rendering and the need for a model. The
method is protected to allow it to be overridden by a custom subclass
that uses a custom descriptor subclass.
- Methods that should not be overridden have been made final.
See gh-73
This commit updates each of the built-in snippet implementations to
provide protected getter methods for their fields. This allows
subclasses to access and work with the snippet’s state.
See gh-73
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, when documenting links, it was necessary to provide the
link extractor that should be used to get the links from the response.
This commit improves on this by adding support for determining the
link extractor to use based on the response's content type. Two
content types are currently supported; application/hal+json and
application/json. For other content types, an extractor can be
provided as before when calling withLinks.
Closes#7
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
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 documentation was handled by using a ResultActions
implementation that had custom methods added to it.
Now documentation is handled using a ResultHandler. This has a few
advantages:
- Fit better with the MockMvc programming model. This is similar to
andDo(print())
- Support for using alwaysDo
Previously, the name of an output file was automatically determined
by the name of the method from which the mockMvc.perform call was made.
While (somewhat) clever, to support this for non @Test methods, this
required the use of a CGLib proxy to push and pop some context that
kept track of the name of the current method. This meant it only worked
for non-private methods. It also made it hard to look at the code and
see what would and would not be documented.
This commit updates the library to provide an explicit document method
instead. This method takes the path of an output directory and a
MockMvc ResultActions instance, typically returned from a call to
mockMvc.perform. For example:
document("index",
this.mockMvc.perform(get("/").accept(MediaTypes.HAL_JSON))
.andExpect(status().isOk()));
This will perform a GET request to "/", assert that the response is
200 OK and write documentation snippets for the request and response
to a directory named index.
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.
