Previously, the included .adoc files did not consistently end with a
blank line. In certain cases, Asciidoctor requires a blank line before a
new section. As a result, the lack of blank lines meant that some
section headings did not appear correctly.
This commit updates each of the included .adoc files in the
documentation to ensure that each ends with a blank line.
Configuring Surefire to run tests found in files ending in
Documentation.java has the unwanted side-effect of switching off its
defaults, i.e. you end up with your documentation tests being run and
nothing else. While using a specific name for your documentation tests
can make them easier to identify, it isn't required. The documentation
also doesn't explicitly recommend using a Documentation suffix.
This commit simplifies things by removing the configuration that
changes Surefire's default inclusions.
Closes gh-368
- Copy snippets used in the tests in @BeforeClass rather than using
Gradle so that the tests can be run easily in an IDE
- Address problems in operation_block_macro.rb reported by Rubocop
- Rename new test class to more closely match the name of the Ruby
class that it’s testing
- Gracefully handle a missing operation
- Align behaviour when an operation or snippet is missing more closely
with Asciidoctor’s behaviour when an include references a missing
file
- Use kebab-case rather than snake_case for new test resources
- Update the documentation to describe the new macro
See gh-354
Closes gh-323
Previously, when a field was documented it would implicitly document
the whole subsection of the payload identified by that field. This
could lead to users inadvertently failing to document part of the
payload. Arguably, this was a bug as it violated REST Docs' principle
of producing accurate, detail documentation. However, fixing it
requires a breaking change as people may also be relying on this
behaviour. A balance needed to be struck so the fix is being made in
a minor release.
This commit introduces a new subsectionWithPath method which returns a
SubsectionDescriptor; a specialisation of FieldDescriptor. Users
that were intentionally relying on the old behaviour will have to
replace some usage of fieldWithPath with subsectionWithPath instead.
Users who were unintentionally relying on the old behaviour will have
to add some additional descriptors produced using fieldWithPath and
will receive more accurate documentation in return.
Closes gh-274
- Rebase on latest code, and make use of new support for the same
TemplatedSnippet producing multiple snippets with different names
from the same template
- Expand the documentation
- Apply code formatting
- Add support for relaxed documentation of a request part's fields
Closes gh-270
Rather than introducing a custom macro, this commit opts to implicitly
configure the snippets attribute instead. The attribute is configured
will the path into which snippets are generated, relative to the
directory that contains the Asciidoctor document that is being
rendered.
The samples and documentation have been updated to use the new
spring-restdocs-asciidoctor module and the implicitly configured
snippets attribute.
Closes gh-297
Rather than requiring an output directory to be explcitly configured,
a default is now automatically configured based on the build tool
that's being used. When using Gradle, snippets will be generated in
build/generated-snippets. When using Maven, snippets will be
generated in target/generated-snippets.
See gh-297
Previously, if alwaysDo was used and the user wanted to generate
one or more additional snippets when calling perform a separate call
to `snippets` was made prior to calling `perform`. This had two
problems:
- it required the result handler to be stateful (see gh-243)
- it wasn't clear that the additional snippets would be produced when
a subsequent call to perform was made
This commit introduces a new API that allows the additional snippets
to be specified within the MockMvc call. The old API has been
deprecated and will be removed in 2.0.
Closes gh-249
This commit adds a new andWithPrefix(String, FieldDescriptor[]) method
to both RequestFieldsSnippet and ResponseFieldsSnippet. It can be
used to add descriptors to an existing snippet, applying the given
prefix to the additional descriptors as it does so. This allows the
descriptors for a portion of a payload to be created once and then
reused, irrespective of where in the payload the portion appears.
Closes gh-221
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
