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
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
The commit introduces OperationPreprocessorAdapter, an abstract
implementation of OperationProcessor that returns to request and
response as-is. OperationPreprocessorAdapter is intended to be
subclassed by OperationProcessor implementations that only modify
the request or the response. Implementations the modify both should
continue to implement OperationPreprocess directly.
Closes gh-154
The HTTP request and response snippets are intended to be an exact
representation of the HTTP request or response which would not wrap.
This commit disables wrapping by adding the nowrap option to the
default templates for these two snippets.
Closes gh-204
This commit updates all of the Snippet implementations that take one
or more descriptors to provide an and method that can be used to
create a new Snippet that has additional descriptors.
Closes gh-168
Add the required blank line between the table "title" and the
table itself. Without this blank line the table wasn't not formatted
correctly. The "title" has also been wrapped in back ticks to improve
its formatting in the generated HTML.
Closes gh-212
This commit polishes the HTTPie request snippet contribution made in
b26d8c0. It makes the following significant changes:
- Applies project’s coding conventions for formatting and the like
- Moves to a composition-based approach for sharing functionality
between the curl and HTTPie snippets by replacing AbstractCliSnippet
with CliOperationRequest.
- Introduces a single package for CLI command snippets, thereby allowing
more code to be package-private.
See gh-207
Previously, both the curl and HTTP request snippets would ignore
a parameter with no value, for example from the query string of the
url http://localhost:8080/foo?bar.
This commit updates both snippets so that such parameters are
included in the generated snippet, including a multi-part request
that is uploading form data and a field in the form has no value.
Additions have been made to the tests for both snippets.
While the request parameters snippet correctly handled parameters with
no value, there was no test verifying that this was the case. One
has been added in this commit.
Closes gh-200
Previously, PrettyPrintingContentModifier would convert the byte[]
content into a String and then back into a byte[]. It did so without
consideration for the content’s character set. As a result, it could
fail to preserve the correct character encoding.
This commit updates PrettyPrintingContentModifier to avoid converting
the content into a String and back into a byte[] and to work entirely
with byte arrays instead. Removing the intermediate String from the
process removes the possibility of the content becoming corrupted.
Closes gh-202
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
