applyPathPrefix is generally useful but, previously, it was only
available as a protected method on AbstractFieldsSnippet.
This commit moves the method from AbstractFieldsSnippet to
PayloadDocumentation where it's now public and static.
Closes gh-245
Previously, when additional snippets were added to a
RestDocumentationResultHandler, those snippets would then be called
for every subsequent call to handle(MvcResult). This is problematic as
the snippets and their configuration are specific to a particular
MvcResult that is being documented.
This commit updates RestDocumentationResultHandler so that it clears
its additional snippets each time handle(MvcResult) is called.
Closes gh-243
Previously, a | character in a cell of an Asciidoctor table would
break that table's formatting as it would be interpretted as a
delimiter for the cell. The problem also affects Markdown tables where
the | character is not within backticks.
This commit addresses the problem with Asciidoctor tables by
introducing a JMustache Lambda that escapes | characters by prefixing
them with a backslash.
Unfortunately, a complete solution to the problem when using Markdown
is not as straightforward. Markdown only requires a | character to be
espaced when it is not within backticks. Determing this isn't
straightforward as the text would have to be parsed, taking into
account the possibility of backticks themselves being escaped.
Instead, this commit attempts to avoid the problem in a different way.
The most likely source of a | character is when documenting a
`@Pattern` constraint that uses a | character in its regular
expression. To improve the readability of the regular expression this
commit wraps it in backticks, thereby formatting it in a monospaced
font in both Asciidoctor and Markdown and also avoiding any escaping
problems with the latter.
Closes gh-232
See gh-230
Previously, the default snippets could only be configured by
replacing those that are configured out of the box. This commit adds
a method, withAdditionalDefaults, that can be used to add one or more
snippets to those that are configured out of the box.
Closes gh-237
This commit updates a number of the snippets to use a monospaced font
for parts of their output. The changes are:
- Links snippet: rel
- Path parameters: name
- Request fields: path and type
- Request headers: name
- Request parameters: name
- Response fields: path and type
- Response headers: name
Closes gh-230
Previously, optional path and request parameter descriptors were
ignored when checking that all of the parameters that are present
had been documented. This lead to a false negative if a request
or path parameter was present and was documented with an optional
descriptor.
This commit uses all of the descriptors, not just those that are not
optional, when checking for undocumented parameters.
Closes gh-228
Previously, many of the snippets would fail when something wasn’t
documented. This worked well when writing exhaustive API documentation,
but was cumbersome when trying to document a scenario that might only
being interested in a subset of the links, response fields, etc. It was
necessary to mark things that were not of interest as being ignored.
This commit introduces a relaxed variant of several snippets. A relaxed
snippet will not fail if something has not been documented. Instead,
the undocumented thing will be ignored. If something has been documented
but it does not exist a failure will still occur.
Closes gh-175
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
