In 1.0, the reliance on JUnit was more widespread than it should have
been. It should have been isolated to the JUnit TestRule implementation,
RestDocumentation. Unfortunately, RestDocumentation was also an argument
to MockMvcRestDocumentation.documentationConfiguration which made it
impossible to use Spring REST Docs without having JUnit on the
classpath.
This commit introduces JUnitRestDocumentation and
ManualRestDocumentation. The format is a direct replacement for
RestDocumentation which has been reworked to delegate to
JUnitRestDocumentation. The latter allows manual management of the
RestDocumentationContext, primarily for use with TestNG.
A new interface, RestDocumentationContextProvider, has been introduced.
It is implemented by RestDocumentation, JUnitRestDocumentation and
ManualRestDocumentation.
MockMvcRestDocumentation.documentationConfiguration has been overridden
to also accept a RestDocumentationContextProvider. The method that
accepts a RestDocumentation has been deprecated, as has
RestDocumentation itself.
The documentation has been updated to encourage the use of
JUnitRestDocumentation and a sample illustrating the use of Spring REST
Docs with TestNG has been added.
Closes gh-171
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
A new preprocessor method `removeMatchingHeaders` has been introduced
which takes one or more regular expression patterns (as Strings). Any
header that matches a pattern is removed.
Closes gh-195
Previously, logic for creating an Operation, determining the snippets
to call, and calling them was duplicated in both the MockMvc and
REST Assured modules. This commit introduces a new core class,
RestDocumentationHandler, that now does the bulk of the work in a
reusable manner. The MockMvc and REST Assured modules have been
updated to delegate to RestDocumentationHandler.
Closes gh-194
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, MustacheTemplateEngine hard coded the configuration of
its Mustache Compiler. This commit adds an overloaded constructor that
allows a custom Compiler to be used. It also adds protected accessors
for the compiler and the template resource resolver so that they
can be easily accessed by subclasses.
Closes gh-149
This commit adds a new module, spring-restdocs-restassured, that
can be used to generate documentation snippets when testing a service
with REST Assured.
Please refer to the updated reference documentation for details.
Thanks to Johan Haleby for making a change to REST Assured so that
path parameters could be documented.
Closes gh-102
This commit adds an Asciidoctor extension that post-processes code
blocks, collapsing any secondary blocks into the preceding primary
block. The primary block is then augmented with a switch. This switch
contains one item for each block. Clicking an item causes the associated
block’s content to be displayed. Each item is named using its block’s
title.
The getting started instructions have been updated to take advantage of
this new switching support, with the Maven and Gradle instructions
being collapsed into a single section.
Closes gh-189
The plugin for building the samples assumed that the current working
directory would be the directory containing the project’s build.gradle.
While this is generally true on the command line (it isn’t if
-project-dir is used), it isn’t true in Gradle’s IDE integration. This
was leading to an NPE as the sampleBuild task was being configured
to depend on a null task as a result of not finding the sample’s pom.xml
or build.grade file.
This commit corrects the main build.gradle to configure each sample’s
working directory relative to the root project’s directory, rather
than relying on the working directory. It also improves
SampleBuildConfigurer so that it will throw an exception if it fails to
find a sample’s build.gradle or pom.xml rather than continuing
and triggering an NPE inside Gradle.
Closes gh-185
