Polish .adoc source files

docs/src/docs/asciidoc/configuration.adoc

@@ -3,11 +3,15 @@
 
 This section covers how to configure Spring REST Docs.
 
+
+
 [[configuration-uris]]
 === Documented URIs
 
 This section covers configuring documented URIs.
 
+
+
 [[configuration-uris-mockmvc]]
 ==== MockMvc URI Customization
 
@@ -30,12 +34,10 @@ This configuration is applied by `MockMvcRestDocumentationConfigurer`.
 You can use its API to change one or more of the defaults to suit your needs.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/mockmvc/CustomUriConfiguration.java[tags=custom-uri-configuration]
 ----
-====
 
 NOTE: If the port is set to the default for the configured scheme (port 80 for HTTP or port 443 for HTTPS), it is omitted from any URIs in the generated snippets.
 
@@ -59,13 +61,11 @@ When using WebTestClient, the default base for URIs documented by Spring REST Do
 You can customize this base by using the {spring-framework-api}/org/springframework/test/web/reactive/server/WebTestClient.Builder.html#baseUrl-java.lang.String-[ `baseUrl(String)` method on `WebTestClient.Builder`].
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/webtestclient/CustomUriConfiguration.java[tags=custom-uri-configuration]
 ----
 <1> Configure the base of documented URIs to be `https://api.example.com`.
-====
 
 
 
@@ -76,7 +76,6 @@ The default snippet encoding is `UTF-8`.
 You can change the default snippet encoding by using the `RestDocumentationConfigurer` API.
 For example, the following examples use `ISO-8859-1`:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -94,7 +93,6 @@ include::{examples-dir}/com/example/webtestclient/CustomEncoding.java[tags=custo
 ----
 include::{examples-dir}/com/example/restassured/CustomEncoding.java[tags=custom-encoding]
 ----
-====
 
 TIP: When Spring REST Docs converts the content of a request or a response to a `String`, the `charset` specified in the `Content-Type` header is used if it is available.
 In its absence, the JVM's default `Charset` is used.
@@ -110,7 +108,6 @@ Markdown is also supported out of the box.
 You can change the default format by using the `RestDocumentationConfigurer` API.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -128,7 +125,6 @@ include::{examples-dir}/com/example/webtestclient/CustomFormat.java[tags=custom-
 ----
 include::{examples-dir}/com/example/restassured/CustomFormat.java[tags=custom-format]
 ----
-====
 
 
 
@@ -147,7 +143,6 @@ Six snippets are produced by default:
 You can change the default snippet configuration during setup by using the `RestDocumentationConfigurer` API.
 The following examples produce only the `curl-request` snippet by default:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -165,7 +160,8 @@ include::{examples-dir}/com/example/webtestclient/CustomDefaultSnippets.java[tag
 ----
 include::{examples-dir}/com/example/restassured/CustomDefaultSnippets.java[tags=custom-default-snippets]
 ----
-====
+
+
 
 [[configuration-default-preprocessors]]
 === Default Operation Preprocessors
@@ -173,7 +169,6 @@ include::{examples-dir}/com/example/restassured/CustomDefaultSnippets.java[tags=
 You can configure default request and response preprocessors during setup by using the `RestDocumentationConfigurer` API.
 The following examples remove the `Foo` headers from all requests and pretty print all responses:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -197,4 +192,5 @@ include::{examples-dir}/com/example/restassured/CustomDefaultOperationPreprocess
 ----
 <1> Apply a request preprocessor that removes the header named `Foo`.
 <2> Apply a response preprocessor that pretty prints its content.
-====
+
+

docs/src/docs/asciidoc/contributing.adoc

@@ -29,3 +29,5 @@ If you would like an enhancement to be made to Spring REST Docs, pull requests a
 The source code is on {github}[GitHub].
 You may want to search the {github}/issues?q=is%3Aissue[existing issues] and {github}/pulls?q=is%3Apr[pull requests] to see if the enhancement has already been proposed.
 You may also want to {github}/issues/new[open a new issue] to discuss a possible enhancement before work on it begins.
+
+

docs/src/docs/asciidoc/customizing-requests-and-responses.adoc

@@ -8,7 +8,6 @@ Preprocessing is configured by calling `document` with an `OperationRequestPrepr
 You can obtain instances by using the static `preprocessRequest` and `preprocessResponse` methods on `Preprocessors`.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -32,13 +31,11 @@ include::{examples-dir}/com/example/restassured/PerTestPreprocessing.java[tags=p
 ----
 <1> Apply a request preprocessor that removes the header named `Foo`.
 <2> Apply a response preprocessor that pretty prints its content.
-====
 
 Alternatively, you may want to apply the same preprocessors to every test.
 You can do so by using the `RestDocumentationConfigurer` API in your `@Before` method to configure the preprocessors.
 For example, to remove the `Foo` header from all requests and pretty print all responses, you could do one of the following (depending on your testing environment):
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -62,12 +59,10 @@ include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags
 ----
 <1> Apply a request preprocessor that removes the header named `Foo`.
 <2> Apply a response preprocessor that pretty prints its content.
-====
 
 Then, in each test, you can perform any configuration specific to that test.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -85,7 +80,6 @@ include::{examples-dir}/com/example/webtestclient/EveryTestPreprocessing.java[ta
 ----
 include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags=use]
 ----
-====
 
 Various built-in preprocessors, including those illustrated above, are available through the static methods on `Preprocessors`.
 See <<Preprocessors, below>> for further details.
@@ -155,3 +149,5 @@ If one of the built-in preprocessors does not meet your needs, you can write you
 You can then use your custom preprocessor in exactly the same way as any of the built-in preprocessors.
 
 If you want to modify only the content (body) of a request or response, consider implementing the `ContentModifier` interface and using it with the built-in `ContentModifyingOperationPreprocessor`.
+
+

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -11,7 +11,6 @@ This section provides more details about using Spring REST Docs to document your
 Spring REST Docs provides support for documenting the links in a https://en.wikipedia.org/wiki/HATEOAS[hypermedia-based] API.
 The following examples show how to use it:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -44,7 +43,6 @@ Uses the static `links` method on `org.springframework.restdocs.hypermedia.Hyper
 <2> Expect a link whose `rel` is `alpha`.
 Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
 <3> Expect a link whose `rel` is `bravo`.
-====
 
 The result is a snippet named `links.adoc` that contains a table describing the resource's links.
 
@@ -76,7 +74,6 @@ Two link formats are understood by default:
 If you use Atom- or HAL-format links but with a different content type, you can provide one of the built-in `LinkExtractor` implementations to `links`.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -100,7 +97,6 @@ include::{examples-dir}/com/example/restassured/Hypermedia.java[tag=explicit-ext
 ----
 <1> Indicate that the links are in HAL format.
 Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
-====
 
 If your API represents its links in a format other than Atom or HAL, you can provide your own implementation of the `LinkExtractor` interface to extract the links from the response.
 
@@ -113,12 +109,10 @@ Rather than documenting links that are common to every response, such as `self`
 To do so, you can build on the <<documenting-your-api-reusing-snippets,support for reusing snippets>> to add link descriptors to a snippet that is preconfigured to ignore certain links.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/Hypermedia.java[tags=ignore-links]
 ----
-====
 
 
 
@@ -139,7 +133,6 @@ To provide more detailed documentation of a request or response payload, support
 
 Consider the following payload:
 
-====
 [source,json,indent=0]
 ----
 	{
@@ -149,11 +142,9 @@ Consider the following payload:
 		}
 	}
 ----
-====
 
 You can document the previous example's fields as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -189,7 +180,6 @@ Both are static methods on `org.springframework.restdocs.payload.PayloadDocument
 <2> Expect a field with the path `contact.email`.
 Uses the static `fieldWithPath` method  on `org.springframework.restdocs.payload.PayloadDocumentation`.
 <3> Expect a field with the path `contact.name`.
-====
 
 The result is a snippet that contains a table describing the fields.
 For requests, this snippet is named `request-fields.adoc`.
@@ -201,7 +191,6 @@ Similarly, the test also fails if a documented field is not found in the payload
 If you do not want to provide detailed documentation for all of the fields, an entire subsection of a payload can be documented.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -228,7 +217,6 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=subsection]
 <1> Document the subsection with the path `contact`.
 `contact.email` and `contact.name` are now seen as having also been documented.
 Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
-====
 
 `subsectionWithPath` can be useful for providing a high-level overview of a particular section of a payload.
 You can then produce separate, more detailed documentation for a subsection.
@@ -244,11 +232,15 @@ This can be useful when documenting a particular scenario where you want to focu
 TIP: By default, Spring REST Docs assumes that the payload you are documenting is JSON.
 If you want to document an XML payload, the content type of the request or response must be compatible with `application/xml`.
 
+
+
 [[documenting-your-api-request-response-payloads-fields-json]]
 ===== Fields in JSON Payloads
 
 This section describes how to work with fields in JSON payloads.
 
+
+
 [[documenting-your-api-request-response-payloads-fields-json-field-paths]]
 ====== JSON Field Paths
 
@@ -261,7 +253,6 @@ The two different notations can be used in the same path (for example, `a['b']`)
 
 Consider the following JSON payload:
 
-====
 [source,json,indent=0]
 ----
 	{
@@ -281,7 +272,6 @@ Consider the following JSON payload:
 		}
 	}
 ----
-====
 
 In the preceding JSON payload, the following paths are all present:
 
@@ -318,7 +308,6 @@ In the preceding JSON payload, the following paths are all present:
 
 |`['a']['e.dot']`
 |The string `four`
-
 |===
 
 You can also document a payload that uses an array at its root.
@@ -326,7 +315,6 @@ The path `[]` refers to the entire array.
 You can then use bracket or dot notation to identify fields within the array's entries.
 For example, `[].id` corresponds to the `id` field of every object found in the following array:
 
-====
 [source,json,indent=0]
 ----
 	[
@@ -338,12 +326,10 @@ For example, `[].id` corresponds to the `id` field of every object found in the
 		}
 	]
 ----
-====
 
 You can use `\*` as a wildcard to match fields with different names.
 For example, `users.*.role` could be used to document the role of every user in the following JSON:
 
-====
 [source,json,indent=0]
 ----
 	{
@@ -357,7 +343,6 @@ For example, `users.*.role` could be used to document the role of every user in
 		}
 	}
 ----
-====
 
 [[documenting-your-api-request-response-payloads-fields-json-field-types]]
 ====== JSON Field Types
@@ -396,7 +381,6 @@ The result of the `toString` method of the supplied `Object` is used in the docu
 Typically, one of the values enumerated by `JsonFieldType` is used.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -417,7 +401,7 @@ include::{examples-dir}/com/example/webtestclient/Payload.java[tags=explicit-typ
 include::{examples-dir}/com/example/restassured/Payload.java[tags=explicit-type]
 ----
 <1> Set the field's type to `String`.
-====
+
 
 
 [[documenting-your-api-request-response-payloads-fields-xml]]
@@ -425,6 +409,8 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=explicit-type]
 
 This section describes how to work with XML payloads.
 
+
+
 [[documenting-your-api-request-response-payloads-fields-xml-field-paths]]
 ====== XML Field Paths
 
@@ -449,7 +435,6 @@ This lets the descriptors for a repeated portion of a request or response payloa
 
 Consider an endpoint that returns a book:
 
-====
 [source,json,indent=0]
 ----
 	{
@@ -457,13 +442,11 @@ Consider an endpoint that returns a book:
 		"author": "Jane Austen"
 	}
 ----
-====
 
 The paths for `title` and `author` are `title` and `author`, respectively.
 
 Now consider an endpoint that returns an array of books:
 
-====
 [source,json,indent=0]
 ----
 	[{
@@ -475,23 +458,19 @@ Now consider an endpoint that returns an array of books:
 		"author": "Harper Lee"
 	}]
 ----
-====
 
 The paths for `title` and `author` are `[].title` and `[].author`, respectively.
 The only difference between the single book and the array of books is that the fields' paths now have a `[].` prefix.
 
 You can create the descriptors that document a book as follows:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/Payload.java[tags=book-descriptors]
 ----
-====
 
 You can then use them to document a single book, as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -512,11 +491,9 @@ include::{examples-dir}/com/example/webtestclient/Payload.java[tags=single-book]
 include::{examples-dir}/com/example/restassured/Payload.java[tags=single-book]
 ----
 <1> Document `title` and `author` by using existing descriptors
-====
 
 You can also use the descriptors to document an array of books, as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -540,7 +517,8 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=book-array]
 ----
 <1> Document the array.
 <2> Document `[].title` and `[].author` by using the existing descriptors prefixed with `[].`
-====
+
+
 
 [[documenting-your-api-request-response-payloads-subsections]]
 ==== Documenting a Subsection of a Request or Response Payload
@@ -548,12 +526,13 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=book-array]
 If a payload is large or structurally complex, it can be useful to document individual sections of the payload.
 REST Docs let you do so by extracting a subsection of the payload and then documenting it.
 
+
+
 [[documenting-your-api-request-response-payloads-subsections-body]]
 ===== Documenting a Subsection of a Request or Response Body
 
 Consider the following JSON response body:
 
-====
 [source,json,indent=0]
 ----
 	{
@@ -569,11 +548,9 @@ Consider the following JSON response body:
 		}
 	}
 ----
-====
 
 You can produce a snippet that documents the `temperature` object as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -600,11 +577,9 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=body-subsectio
 <1> Produce a snippet containing a subsection of the response body.
 Uses the static `responseBody` and `beneathPath` methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
 To produce a snippet for the request body, you can use `requestBody` in place of `responseBody`.
-====
 
 The result is a snippet with the following contents:
 
-====
 [source,json,indent=0]
 ----
 	{
@@ -614,19 +589,16 @@ The result is a snippet with the following contents:
 		}
 	}
 ----
-====
 
 To make the snippet's name distinct, an identifier for the subsection is included.
 By default, this identifier is `beneath-${path}`.
 For example, the preceding code results in a snippet named `response-body-beneath-weather.temperature.adoc`.
 You can customize the identifier by using the `withSubsectionId(String)` method, as follows:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/Payload.java[tags=custom-subsection-id]
 ----
-====
 
 The result is a snippet named `request-body-temp.adoc`.
 
@@ -638,7 +610,6 @@ The result is a snippet named `request-body-temp.adoc`.
 As well as documenting a subsection of a request or response body, you can also document the fields in a particular subsection.
 You can produce a snippet that documents the fields of the `temperature` object (`high` and `low`) as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -665,7 +636,6 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=fields-subsect
 <1> Produce a snippet describing the fields in the subsection of the response payload beneath the path `weather.temperature`.
 Uses the static `beneathPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
 <2> Document the `high` and `low` fields.
-====
 
 The result is a snippet that contains a table describing the `high` and `low` fields of `weather.temperature`.
 To make the snippet's name distinct, an identifier for the subsection is included.
@@ -681,7 +651,6 @@ You can document a request's parameters by using `requestParameters`.
 You can include request parameters in a `GET` request's query string.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -717,12 +686,10 @@ Uses the static `requestParameters` method on `org.springframework.restdocs.requ
 Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <3> Document the `per_page` parameter.
 <4> Perform a `GET` request with two parameters, `page` and `per_page`, in the query string.
-====
 
 You can also include request parameters as form data in the body of a POST request.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -744,7 +711,6 @@ include::{examples-dir}/com/example/restassured/RequestParameters.java[tags=requ
 ----
 <1> Configure the `username` parameter.
 <2> Perform the `POST` request.
-====
 
 In all cases, the result is a snippet named `request-parameters.adoc` that contains a table describing the parameters that are supported by the resource.
 
@@ -766,7 +732,6 @@ This can be useful when documenting a particular scenario where you only want to
 You can document a request's path parameters by using `pathParameters`.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -802,7 +767,6 @@ Uses the static `pathParameters` method on `org.springframework.restdocs.request
 Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <3> Document the parameter named `longitude`.
 <4> Perform a `GET` request with two path parameters, `latitude` and `longitude`.
-====
 
 The result is a snippet named `path-parameters.adoc` that contains a table describing the path parameters that are supported by the resource.
 
@@ -826,7 +790,6 @@ Doing so prevents it from appearing in the generated snippet while avoiding the
 You can use `requestParts` to document the parts of a multipart request.
 The following example shows how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -860,7 +823,6 @@ Uses the static `requestParts` method on `org.springframework.restdocs.request.R
 Uses the static `partWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
 <3> Configure the request with the part named `file`.
 <4> Perform the `POST` request to `/upload`.
-====
 
 The result is a snippet named `request-parts.adoc` that contains a table describing the request parts that are supported by the resource.
 
@@ -875,6 +837,7 @@ If you do not want to document a request part, you can mark it as ignored.
 This prevents it from appearing in the generated snippet while avoiding the failure described earlier.
 
 
+
 [[documenting-your-api-request-parts-payloads]]
 === Request Part Payloads
 
@@ -887,7 +850,6 @@ You can document the payload of a request part in much the same way as the <<doc
 
 You can generate a snippet containing the body of a request part as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -911,7 +873,6 @@ include::{examples-dir}/com/example/restassured/RequestPartPayload.java[tags=bod
 ----
 <1> Configure Spring REST docs to produce a snippet containing the body of the request part named `metadata`.
 Uses the static `requestPartBody` method on `PayloadDocumentation`.
-====
 
 The result is a snippet named `request-part-${part-name}-body.adoc` that contains the part's body.
 For example, documenting a part named `metadata` produces a snippet named `request-part-metadata-body.adoc`.
@@ -923,7 +884,6 @@ For example, documenting a part named `metadata` produces a snippet named `reque
 
 You can document a request part's fields in much the same way as the fields of a request or response, as follows:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -953,7 +913,6 @@ include::{examples-dir}/com/example/restassured/RequestPartPayload.java[tags=fie
 Uses the static `requestPartFields` method on `PayloadDocumentation`.
 <2> Expect a field with the path `version`.
 Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
-====
 
 The result is a snippet that contains a table describing the part's fields.
 This snippet is named `request-part-${part-name}-fields.adoc`.
@@ -972,13 +931,14 @@ This can be useful when documenting a particular scenario where you only want to
 
 For further information on describing fields, documenting payloads that use XML, and more, see the <<documenting-your-api-request-response-payloads,section on documenting request and response payloads>>.
 
+
+
 [[documenting-your-api-http-headers]]
 === HTTP Headers
 
 You can document the headers in a request or response by using `requestHeaders` and `responseHeaders`, respectively.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -1017,7 +977,6 @@ Uses the static `headerWithName` method on `org.springframework.restdocs.headers
 <3> Produce a snippet describing the response's headers.
 Uses the static `responseHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`.
 <4> Configure the request with an `Authorization` header that uses basic authentication.
-====
 
 The result is a snippet named `request-headers.adoc` and a snippet named `response-headers.adoc`.
 Each contains a table describing the headers.
@@ -1035,17 +994,14 @@ To avoid repetition when documenting such resources, you can reuse a `Snippet` c
 First, create the `Snippet` that describes the common elements.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/SnippetReuse.java[tags=field]
 ----
-====
 
 Second, use this snippet and add further descriptors that are resource-specific.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -1066,7 +1022,6 @@ include::{examples-dir}/com/example/webtestclient/WebTestClientSnippetReuse.java
 include::{examples-dir}/com/example/restassured/RestAssuredSnippetReuse.java[tags=use]
 ----
 <1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific to the resource that is being documented.
-====
 
 The result of the example is that links with `rel` values of `first`, `last`, `next`, `previous`, `alpha`, and `bravo` are all documented.
 
@@ -1079,7 +1034,6 @@ Spring REST Docs provides a number of classes that can help you to document cons
 You can use an instance of `ConstraintDescriptions` to access descriptions of a class's constraints.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/Constraints.java[tags=constraints]
@@ -1087,7 +1041,6 @@ include::{examples-dir}/com/example/Constraints.java[tags=constraints]
 <1> Create an instance of `ConstraintDescriptions` for the `UserInput` class.
 <2> Get the descriptions of the `name` property's constraints.
 This list contains two descriptions: one for the `NotNull` constraint and one for the `Size` constraint.
-====
 
 The {samples}/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java[`ApiDocumentation`] class in the Spring HATEOAS sample shows this functionality in action.
 
@@ -1201,7 +1154,6 @@ call that is being documented.
 
 | `response-body.adoc`
 | Contains the body of the response that was returned.
-
 |===
 
 You can configure which snippets are produced by default.
@@ -1249,7 +1201,6 @@ A parameterized output directory is particularly useful in combination with a `@
 It lets documentation be configured once in a setup method and then reused in every test in the class.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -1267,7 +1218,6 @@ include::{examples-dir}/com/example/restassured/ParameterizedOutput.java[tags=pa
 ----
 include::{examples-dir}/com/example/webtestclient/ParameterizedOutput.java[tags=parameterized-output]
 ----
-====
 
 With this configuration in place, every call to the service you are testing produces the <<documenting-your-api-default-snippets,default snippets>> without any further configuration.
 Take a look at the `GettingStartedDocumentation` classes in each of the sample applications to see this functionality in action.
@@ -1279,6 +1229,8 @@ Take a look at the `GettingStartedDocumentation` classes in each of the sample a
 
 This section describes how to customize the output of Spring REST Docs.
 
+
+
 [[documenting-your-api-customizing-snippets]]
 ==== Customizing the Generated Snippets
 
@@ -1310,7 +1262,6 @@ A concrete example is the addition of a constraints column and a title when docu
 The first step is to provide a `constraints` attribute for each field that you document and to provide a `title` attribute.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -1337,12 +1288,10 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=constraints]
 <1> Configure the `title` attribute for the request fields snippet.
 <2> Set the `constraints` attribute for the `name` field.
 <3> Set the `constraints` attribute for the `email` field.
-====
 
 The second step is to provide a custom template named `request-fields.snippet` that includes the information about the fields' constraints in the generated snippet's table and adds a title.
 The following example shows how to do so:
 
-====
 [source,indent=0]
 ----
 	.{{title}} <1>
@@ -1361,4 +1310,6 @@ The following example shows how to do so:
 <1> Add a title to the table.
 <2> Add a new column named "Constraints".
 <3> Include the descriptors' `constraints` attribute in each row of the table.
-====
+
+
+

docs/src/docs/asciidoc/getting-started.adoc

@@ -22,7 +22,6 @@ If you want to jump straight in, a number of sample applications are available:
 | {samples}/rest-notes-spring-hateoas[Spring HATEOAS]
 | Gradle
 | Demonstrates the creation of a getting started guide and an API guide for a service implemented by using https://projects.spring.io/spring-hateoas/[Spring HATEOAS].
-
 |===
 
 [cols="3,2,10"]
@@ -33,7 +32,6 @@ If you want to jump straight in, a number of sample applications are available:
 | {samples}/web-test-client[WebTestClient]
 | Gradle
 | Demonstrates the use of Spring REST docs with Spring WebFlux's WebTestClient.
-
 |===
 
 
@@ -45,7 +43,6 @@ If you want to jump straight in, a number of sample applications are available:
 | {samples}/rest-assured[REST Assured]
 | Gradle
 | Demonstrates the use of Spring REST Docs with http://rest-assured.io[REST Assured].
-
 |===
 
 
@@ -66,9 +63,10 @@ If you want to jump straight in, a number of sample applications are available:
 | {samples}/junit5[JUnit 5]
 | Gradle
 | Demonstrates the use of Spring REST Docs with https://junit.org/junit5/[JUnit 5].
-
 |===
 
+
+
 [[getting-started-requirements]]
 === Requirements
 
@@ -79,6 +77,8 @@ Spring REST Docs has the following minimum requirements:
 
 Additionally, the `spring-restdocs-restassured` module requires REST Assured 3.0.
 
+
+
 [[getting-started-build-configuration]]
 === Build configuration
 
@@ -86,7 +86,6 @@ The first step in using Spring REST Docs is to configure your project's build.
 The {samples}/rest-notes-spring-hateoas[Spring HATEOAS] and {samples}/rest-notes-spring-data-rest[Spring Data REST] samples contain a `build.gradle` and `pom.xml`, respectively, that you may wish to use as a reference.
 The key parts of the configuration are described in the following listings:
 
-====
 [source,xml,indent=0,subs="verbatim,attributes",role="primary"]
 .Maven
 ----
@@ -178,7 +177,8 @@ If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a de
 <8> Configure the snippets directory as an input.
 <9> Configure the use of the `asciidoctorExt` configuration for extensions.
 <10> Make the task depend on the test task so that the tests are run before the documentation is created.
-====
+
+
 
 [[getting-started-build-configuration-packaging-the-documentation]]
 ==== Packaging the Documentation
@@ -191,7 +191,6 @@ To do so, configure your project's build so that:
 
 The following listings show how to do so in both Maven and Gradle:
 
-====
 [source,xml,indent=0,role="primary"]
 .Maven
 ----
@@ -242,7 +241,6 @@ The following listings show how to do so in both Maven and Gradle:
 ----
 <1> Ensure that the documentation has been generated before the jar is built.
 <2> Copy the generated documentation into the jar's `static/docs` directory.
-====
 
 
 
@@ -261,19 +259,19 @@ Exactly how you set up your tests depends on the test framework that you use.
 Spring REST Docs provides first-class support for JUnit 4 and JUnit 5.
 Other frameworks, such as TestNG, are also supported, although slightly more setup is required.
 
+
+
 [[getting-started-documentation-snippets-setup-junit]]
 ===== Setting up Your JUnit 4 Tests
 
 When using JUnit 4, the first step in generating documentation snippets is to declare a `public` `JUnitRestDocumentation` field that is annotated as a JUnit `@Rule`.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 @Rule
 public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 ----
-====
 
 By default, the `JUnitRestDocumentation` rule is automatically configured with an output directory based on your project's build tool:
 
@@ -286,24 +284,20 @@ By default, the `JUnitRestDocumentation` rule is automatically configured with a
 
 | Gradle
 | `build/generated-snippets`
-
 |===
 
 You can override the default by providing an output directory when you create the `JUnitRestDocumentation` instance.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 @Rule
 public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
 ----
-====
 
 Next, you must provide an `@Before` method to configure MockMvc, WebTestClient or REST Assured.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -327,7 +321,6 @@ include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tag
 ----
 <1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured3` package.
-====
 
 The configurer applies sensible defaults and also provides an API for customizing the configuration.
 See the <<configuration, configuration section>> for more information.
@@ -340,23 +333,19 @@ See the <<configuration, configuration section>> for more information.
 When using JUnit 5, the first step in generating documentation snippets is to apply the `RestDocumentationExtension` to your test class.
 The following example shows how to do so:
 
-====
 [source,java,indent=0]
 ----
 @ExtendWith(RestDocumentationExtension.class)
 public class JUnit5ExampleTests {
 ----
-====
 
 When testing a typical Spring application, you should also apply the `SpringExtension`:
 
-====
 [source,java,indent=0]
 ----
 @ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
 public class JUnit5ExampleTests {
 ----
-====
 
 The `RestDocumentationExtension` is automatically configured with an output directory based on your project's build tool:
 
@@ -369,7 +358,6 @@ The `RestDocumentationExtension` is automatically configured with an output dire
 
 | Gradle
 | `build/generated-snippets`
-
 |===
 
 If you are using JUnit 5.1, you can override the default by registering the extension as a field in your test class and providing an output directory when creating it.
@@ -388,7 +376,6 @@ public class JUnit5ExampleTests {
 Next, you must provide a `@BeforeEach` method to configure MockMvc, WebTestClient, or REST Assured.
 The following listings show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -412,15 +399,14 @@ include::{examples-dir}/com/example/restassured/ExampleApplicationJUnit5Tests.ja
 ----
 <1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured3` package.
-====
 
 The configurer applies sensible defaults and also provides an API for customizing the configuration.
 See the <<configuration, configuration section>> for more information.
 
 
 
-===== Setting up your tests without JUnit
 [[getting-started-documentation-snippets-setup-manual]]
+===== Setting up your tests without JUnit
 
 The configuration when JUnit is not being used is largely similar to when it is being used.
 This section describes the key differences.
@@ -430,18 +416,15 @@ The first difference is that you should use `ManualRestDocumentation` in place o
 Also, you do not need the `@Rule` annotation.
 The following example shows how to use `ManualRestDocumentation`:
 
-====
 [source,java,indent=0]
 ----
 private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
 ----
-====
 
 Secondly, you must call `ManualRestDocumentation.beforeTest(Class, String)` before each test.
 You can do so as part of the method that configures MockMvc, WebTestClient, or REST Assured.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -459,17 +442,16 @@ include::{examples-dir}/com/example/webtestclient/ExampleApplicationTestNgTests.
 ----
 include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.java[tags=setup]
 ----
-====
 
 Finally, you must call `ManualRestDocumentation.afterTest` after each test.
 The following example shows how to do so with TestNG:
 
-====
 [source,java,indent=0]
 ----
 include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.java[tags=teardown]
 ----
-====
+
+
 
 [[getting-started-documentation-snippets-invoking-the-service]]
 ==== Invoking the RESTful Service
@@ -477,7 +459,6 @@ include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.ja
 Now that you have configured the testing framework, you can use it to invoke the RESTful service and document the request and response.
 The following examples show how to do so:
 
-====
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
@@ -512,7 +493,6 @@ The snippets are written by a `RestDocumentationFilter`.
 You can obtain an instance of this class from the static `document` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured3` package.
 <4> Invoke the root (`/`) of the service.
 <5> Assert that the service produce the expected response.
-====
 
 By default, six snippets are written:
 
@@ -546,16 +526,15 @@ The default location of the source files and the resulting HTML files depends on
 | Gradle
 | `src/docs/asciidoc/*.adoc`
 | `build/asciidoc/html5/*.html`
-
 |===
 
 You can then include the generated snippets in the manually created Asciidoc file (described earlier in this section) by using the https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include macro].
 You can use the `snippets` attribute that is automatically set by `spring-restdocs-asciidoctor` configured in the <<getting-started-build-configuration,build configuration>> to reference the snippets output directory.
 The following example shows how to do so:
 
-====
 [source,adoc,indent=0]
 ----
 \include::{snippets}/index/curl-request.adoc[]
 ----
-====
+
+

docs/src/docs/asciidoc/introduction.adoc

@@ -18,3 +18,5 @@ Two key parts of each resource's description are the details of the HTTP request
 Spring REST Docs lets you work with these resources and the HTTP requests and responses, shielding your documentation from the inner-details of your service's implementation.
 This separation helps you document your service's API rather than its implementation.
 It also frees you to evolve the implementation without having to rework the documentation.
+
+

docs/src/docs/asciidoc/working-with-asciidoctor.adoc

@@ -21,6 +21,8 @@ Asciidoctor is the tool that produces content (usually as HTML) from Asciidoc fi
 
 This section covers how to include Asciidoc snippets.
 
+
+
 [[working-with-asciidoctor-including-snippets-operation]]
 ==== Including Multiple Snippets for an Operation
 
@@ -30,12 +32,10 @@ It is made available by including `spring-restdocs-asciidoctor` in your project'
 The target of the macro is the name of the operation.
 In its simplest form, you can use the macro to include all of the snippets for an operation, as shown in the following example:
 
-====
 [source,indent=0]
 ----
 operation::index[]
 ----
-====
 
 You can use the operation macro also supports a `snippets` attribute.
 The `snippets` attribute to select the snippets that should be included.
@@ -43,16 +43,13 @@ The attribute's value is a comma-separated list.
 Each entry in the list should be the name of a snippet file (minus the `.adoc` suffix) to include.
 For example, only the curl, HTTP request, and HTTP response snippets can be included, as shown in the following example:
 
-====
 [source,indent=0]
 ----
 operation::index[snippets='curl-request,http-request,http-response']
 ----
-====
 
 The preceding example is the equivalent of the following:
 
-====
 [source,adoc,indent=0]
 ----
 [[example_curl_request]]
@@ -71,7 +68,8 @@ The preceding example is the equivalent of the following:
 \include::{snippets}/index/http-response.adoc[]
 
 ----
-====
+
+
 
 [[working-with-asciidoctor-including-snippets-operation-titles]]
 ===== Section Titles
@@ -117,12 +115,10 @@ You can customize the default titles by using document attributes.
 The name of the attribute should be `operation-{snippet}-title`.
 For example, to customize the title of the `curl-request` snippet to be "Example request", you can use the following attribute:
 
-====
 [source,indent=0]
 ----
 :operation-curl-request-title: Example request
 ----
-====
 
 
 
@@ -133,12 +129,10 @@ The https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[
 You can use the `snippets` attribute (which is automatically set by `spring-restdocs-asciidoctor` configured in the <<getting-started-build-configuration, build configuration>>) to reference the snippets output directory.
 The following example shows how to do so:
 
-====
 [source,indent=0]
 ----
 \include::{snippets}/index/curl-request.adoc[]
 ----
-====
 
 
 
@@ -156,14 +150,12 @@ The appearance of the table can be customized, either by providing some addition
 Asciidoctor has rich support for https://asciidoctor.org/docs/user-manual/#cols-format[formatting a table's columns].
 As the following example shows, you can specify the widths of a table's columns by using the `cols` attribute:
 
-====
 [source,indent=0]
 ----
 [cols="1,3"] <1>
 \include::{snippets}/index/links.adoc[]
 ----
 <1> The table's width is split across its two columns, with the second column being three times as wide as the first.
-====
 
 
 
@@ -173,14 +165,12 @@ As the following example shows, you can specify the widths of a table's columns
 You can specify the title of a table by using a line prefixed by a `.`.
 The following example shows how to do so:
 
-====
 [source,indent=0]
 ----
 .Links <1>
 \include::{snippets}/index/links.adoc[]
 ----
 <1> The table's title will be `Links`.
-====
 
 
 
@@ -195,14 +185,14 @@ All of the default Asciidoctor snippet templates perform this escaping automatic
 If you write your own custom templates you may want to use this lamba.
 The following example shows how to escape `|` characters in a cell that contains the value of a `description` attribute:
 
-====
 ----
 | {{#tableCellContent}}{{description}}{{/tableCellContent}}
 ----
-====
 
 
-
-==== Further Reading
+[[working-with-asciidoctor-further-reading]]
+=== Further Reading
 
 See the https://asciidoctor.org/docs/user-manual/#tables[Tables section of the Asciidoctor user manual] for more information about customizing tables.
+
+

docs/src/docs/asciidoc/working-with-markdown.adoc

@@ -22,3 +22,5 @@ Spring REST Docs' default Markdown snippet templates use https://michelf.ca/proj
 Markdown has no built-in support for including one Markdown file in another.
 To include the generated snippets of Markdown in your documentation, you should use an additional tool that supports this functionality.
 One example that is particularly well-suited to documenting APIs is https://github.com/tripit/slate[Slate].
+
+