Spring REST Docs 1.2 Release Notes
REST Docs will now automatically configure the snippet output directory based on the build system that you’re using:
| Build system | Output directory |
|---|---|
Maven |
|
Gradle |
|
This allows the configuration of the output directory to be removed from the configuration of JUnitRestDocumentation.
A new module, spring-restdocs-asciidoctor has been introduced. It provides some Asciidoctor extensions that make REST Docs and Asciidoctor easier to use together.
A new block macro named operation has been introduced. It can be used to include multiple snippets for the same operation in a single line. Please see this commit that updated the samples to use the macro for an example of its adoption.
A {snippets} document attribute is automatically configured with the value of the convention-based snippet output directory. It can be used when including individual snippets in your documentation.
To make it easier to document large or structurally complex payloads, REST Docs now allows you to document the fields in a subsection of the payload.
Snippets containing the body of the request (request-body.adoc) and response (response-body.adoc) have been introduced. These snippets are enabled by default and no configuration is required to use them. They can also be used explicitly if you want to produce a snippet that contains a subsection of a request or request body.
A new snippet has been introduced that can be used to document the fields of a request part.
Cookies will now be included in the curl and HTTPie request snippets and will appear in the Cookie and Set-Cookie headers of the HTTP request and HTTP response snippets respectively.
A * wildcard can now be used in a field path to document a JSON payload where the keys in a map are variable.
The formatting of the curl and HTTPie commands is now configurable. By default it will be split across multiple lines to aid readability.
In REST Docs 1.1 and earlier, when a field was documented anything nested beneath that field was also considered to have been documented. This was useful in some cases but also led to some fields being inadvertently left undocumented. REST Docs 1.2 changes this behavior so that documenting a field no longer documents everything nested beneath it.
If you were relying on the old behaviour, you can use subsectionWithPath to document a whole subsection of a payload.