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, 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
- Correct the location of the Git repository
- Correct the location of the sample within the repository
- Update the build instructions for the Data REST sample to use Maven
- Move the table of contents to the left
- Add section links
Closes gh-113
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
This commit enhances the tasks that build the samples to
automatically update the version of their spring-restdocs dependency
to match the version of the main project.
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
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
Windows uses \r\n for line endings whereas Unix-like platforms us
\n. This causes the content length of a pretty-printed response to
be longer on Windows.
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.
Previously each sample was built with both Maven and Gradle and the
snippets produced by each build were verified. Now each sample is only
built with either Maven or Gradle. This commit updates the snippet
verification process to look for snippets in the location that’s
appropriate for the sample’s build system.
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
The ordering of parameters in the path is important so, without seeing
the path and the order in which the parameters appear, documentation for
the individual parameters is of limited use.
This commit enhances the path parameters snippet to include the
request’s path, minus any query string, in the snippet. By default,
the path is rendered as the title of the parameters table. As with
other snippets, this can be customized by providing a custom template
for the snippet.
Closes gh-103
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
Previously, SnippetWritingResultHandler hard-coded its own logic for
creating the Writer that used to write its snippet. This made it
impossible to take complete control over the output location, filename
suffix, etc.
This commit introduces a new interface, WriterResolver, and a default
implementation, StandardWriterResolver. It provides the same
functionality as before, but SnippetWritingResultHandler now
retrieves an instance of WriterResolver from the request's attributes.
This allows users to provide their own WriterResolver implementation.
Closes gh-100
