diff --git a/docs/src/docs/asciidoc/documenting-your-api.adoc b/docs/src/docs/asciidoc/documenting-your-api.adoc index 70badfa8..862f1b6f 100644 --- a/docs/src/docs/asciidoc/documenting-your-api.adoc +++ b/docs/src/docs/asciidoc/documenting-your-api.adoc @@ -19,10 +19,10 @@ The following examples show how to use it: include::{examples-dir}/com/example/mockmvc/Hypermedia.java[tag=links] ---- <1> Configure Spring REST docs to produce a snippet describing the response's links. - Uses the static `links` method on - `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +Uses the static `links` method on +`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. <2> Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on - `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. <3> Expect a link whose `rel` is `bravo`. [source,java,indent=0,role="secondary"] @@ -31,10 +31,10 @@ include::{examples-dir}/com/example/mockmvc/Hypermedia.java[tag=links] include::{examples-dir}/com/example/webtestclient/Hypermedia.java[tag=links] ---- <1> Configure Spring REST docs to produce a snippet describing the response's links. - Uses the static `links` method on - `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +Uses the static `links` method on +`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. <2> Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on - `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +`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 @@ -152,10 +152,10 @@ You can document the previous example's fields as follows: include::{examples-dir}/com/example/mockmvc/Payload.java[tags=response] ---- <1> Configure Spring REST docs to produce a snippet describing the fields in the response - payload. To document a request, you can use `requestFields`. Both are static methods - on `org.springframework.restdocs.payload.PayloadDocumentation`. +payload. To document a request, you can use `requestFields`. Both are static methods on +`org.springframework.restdocs.payload.PayloadDocumentation`. <2> Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method - on `org.springframework.restdocs.payload.PayloadDocumentation`. +on `org.springframework.restdocs.payload.PayloadDocumentation`. <3> Expect a field with the path `contact.name`. [source,java,indent=0,role="secondary"] @@ -164,10 +164,10 @@ include::{examples-dir}/com/example/mockmvc/Payload.java[tags=response] include::{examples-dir}/com/example/webtestclient/Payload.java[tags=response] ---- <1> Configure Spring REST docs to produce a snippet describing the fields in the response - payload. To document a request, you can use `requestFields`. Both are static methods - on `org.springframework.restdocs.payload.PayloadDocumentation`. +payload. To document a request, you can use `requestFields`. Both are static methods on +`org.springframework.restdocs.payload.PayloadDocumentation`. <2> Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method - on `org.springframework.restdocs.payload.PayloadDocumentation`. +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 @@ -188,8 +188,8 @@ subsection of a payload can be documented. The following examples show how to do include::{examples-dir}/com/example/mockmvc/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`. +are now seen as having also been documented. Uses the static `subsectionWithPath` method +on `org.springframework.restdocs.payload.PayloadDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient @@ -197,8 +197,8 @@ include::{examples-dir}/com/example/mockmvc/Payload.java[tags=subsection] include::{examples-dir}/com/example/webtestclient/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`. +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 @@ -486,7 +486,7 @@ include::{examples-dir}/com/example/mockmvc/Payload.java[tags=book-array] ---- <1> Document the array. <2> Document `[].title` and `[].author` by using the existing descriptors prefixed with - `[].` +`[].` [source,java,indent=0,role="secondary"] .WebTestClient @@ -495,7 +495,7 @@ include::{examples-dir}/com/example/webtestclient/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 @@ -536,9 +536,9 @@ You can produce a snippet that documents the `temperature` object as follows: include::{examples-dir}/com/example/mockmvc/Payload.java[tags=body-subsection] ---- <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`. +`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`. [source,java,indent=0,role="secondary"] .WebTestClient @@ -546,9 +546,9 @@ include::{examples-dir}/com/example/mockmvc/Payload.java[tags=body-subsection] include::{examples-dir}/com/example/webtestclient/Payload.java[tags=body-subsection] ---- <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`. +`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: @@ -630,12 +630,12 @@ do so: include::{examples-dir}/com/example/mockmvc/RequestParameters.java[tags=request-parameters-query-string] ---- <1> Perform a `GET` request with two parameters, `page` and `per_page`, in the query - string. +string. <2> Configure Spring REST Docs to produce a snippet describing the request's parameters. - Uses the static `requestParameters` method on - `org.springframework.restdocs.request.RequestDocumentation`. +Uses the static `requestParameters` method on +`org.springframework.restdocs.request.RequestDocumentation`. <3> Document the `page` parameter. Uses the static `parameterWithName` method on - `org.springframework.restdocs.request.RequestDocumentation`. +`org.springframework.restdocs.request.RequestDocumentation`. <4> Document the `per_page` parameter. [source,java,indent=0,role="secondary"] @@ -644,12 +644,12 @@ include::{examples-dir}/com/example/mockmvc/RequestParameters.java[tags=request- include::{examples-dir}/com/example/webtestclient/RequestParameters.java[tags=request-parameters-query-string] ---- <1> Perform a `GET` request with two parameters, `page` and `per_page`, in the query - string. +string. <2> Configure Spring REST Docs to produce a snippet describing the request's parameters. - Uses the static `requestParameters` method on - `org.springframework.restdocs.request.RequestDocumentation`. +Uses the static `requestParameters` method on +`org.springframework.restdocs.request.RequestDocumentation`. <3> Document the `page` parameter. Uses the static `parameterWithName` method on - `org.springframework.restdocs.request.RequestDocumentation`. +`org.springframework.restdocs.request.RequestDocumentation`. <4> Document the `per_page` parameter. You can also include request parameters as form data in the body of a POST request. The @@ -703,10 +703,10 @@ include::{examples-dir}/com/example/mockmvc/PathParameters.java[tags=path-parame ---- <1> Perform a `GET` request with two path parameters, `latitude` and `longitude`. <2> Configure Spring REST Docs to produce a snippet describing the request's path - parameters. Uses the static `pathParameters` method on - `org.springframework.restdocs.request.RequestDocumentation`. +parameters. Uses the static `pathParameters` method on +`org.springframework.restdocs.request.RequestDocumentation`. <3> Document the parameter named `latitude`. Uses the static `parameterWithName` method on - `org.springframework.restdocs.request.RequestDocumentation`. +`org.springframework.restdocs.request.RequestDocumentation`. <4> Document the parameter named `longitude`. [source,java,indent=0,role="secondary"] @@ -716,10 +716,10 @@ include::{examples-dir}/com/example/webtestclient/PathParameters.java[tags=path- ---- <1> Perform a `GET` request with two path parameters, `latitude` and `longitude`. <2> Configure Spring REST Docs to produce a snippet describing the request's path - parameters. Uses the static `pathParameters` method on - `org.springframework.restdocs.request.RequestDocumentation`. +parameters. Uses the static `pathParameters` method on +`org.springframework.restdocs.request.RequestDocumentation`. <3> Document the parameter named `latitude`. Uses the static `parameterWithName` method on - `org.springframework.restdocs.request.RequestDocumentation`. +`org.springframework.restdocs.request.RequestDocumentation`. <4> Document the parameter named `longitude`. The result is a snippet named `path-parameters.adoc` that contains a table describing @@ -759,10 +759,10 @@ include::{examples-dir}/com/example/mockmvc/RequestParts.java[tags=request-parts ---- <1> Perform a `POST` request with a single part named `file`. <2> Configure Spring REST Docs to produce a snippet describing the request's parts. Uses - the static `requestParts` method on - `org.springframework.restdocs.request.RequestDocumentation`. +the static `requestParts` method on +`org.springframework.restdocs.request.RequestDocumentation`. <3> Document the part named `file`. Uses the static `partWithName` method on - `org.springframework.restdocs.request.RequestDocumentation`. +`org.springframework.restdocs.request.RequestDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient @@ -771,10 +771,10 @@ include::{examples-dir}/com/example/webtestclient/RequestParts.java[tags=request ---- <1> Perform a `POST` request with a single part named `file`. <2> Configure Spring REST Docs to produce a snippet describing the request's parts. Uses - the static `requestParts` method on - `org.springframework.restdocs.request.RequestDocumentation`. +the static `requestParts` method on +`org.springframework.restdocs.request.RequestDocumentation`. <3> Document the part named `file`. Uses the static `partWithName` method on - `org.springframework.restdocs.request.RequestDocumentation`. +`org.springframework.restdocs.request.RequestDocumentation`. The result is a snippet named `request-parts.adoc` that contains a table describing the request parts that are supported by the resource. @@ -845,10 +845,10 @@ or response, as follows: include::{examples-dir}/com/example/mockmvc/RequestPartPayload.java[tags=fields] ---- <1> Configure Spring REST docs to produce a snippet describing the fields in the payload - of the request part named `metadata`. Uses the static `requestPartFields` method on - `PayloadDocumentation`. +of the request part named `metadata`. 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`. +`org.springframework.restdocs.payload.PayloadDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient @@ -856,10 +856,10 @@ include::{examples-dir}/com/example/mockmvc/RequestPartPayload.java[tags=fields] include::{examples-dir}/com/example/webtestclient/RequestPartPayload.java[tags=fields] ---- <1> Configure Spring REST docs to produce a snippet describing the fields in the payload - of the request part named `metadata`. Uses the static `requestPartFields` method on - `PayloadDocumentation`. +of the request part named `metadata`. 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`. +`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`. For example, documenting a part named @@ -896,28 +896,30 @@ You can document the headers in a request or response by using `requestHeaders` ---- include::{examples-dir}/com/example/mockmvc/HttpHeaders.java[tags=headers] ---- -<1> Perform a `GET` request with an `Authorization` header that uses basic authentication. +<1> Perform a `GET` request with an `Authorization` header that uses basic +authentication. <2> Configure Spring REST Docs to produce a snippet describing the request's headers. - Uses the static `requestHeaders` method on - `org.springframework.restdocs.headers.HeaderDocumentation`. +Uses the static `requestHeaders` method on +`org.springframework.restdocs.headers.HeaderDocumentation`. <3> Document the `Authorization` header. Uses the static `headerWithName` method on - `org.springframework.restdocs.headers.HeaderDocumentation`. -<4> Produce a snippet describing the response's headers. Uses the static `responseHeaders` - method on `org.springframework.restdocs.headers.HeaderDocumentation`. +`org.springframework.restdocs.headers.HeaderDocumentation`. +<4> Produce a snippet describing the response's headers. Uses the static +`responseHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/HttpHeaders.java[tags=headers] ---- -<1> Perform a `GET` request with an `Authorization` header that uses basic authentication. +<1> Perform a `GET` request with an `Authorization` header that uses basic +authentication. <2> Configure Spring REST Docs to produce a snippet describing the request's headers. - Uses the static `requestHeaders` method on - `org.springframework.restdocs.headers.HeaderDocumentation`. +Uses the static `requestHeaders` method on +`org.springframework.restdocs.headers.HeaderDocumentation`. <3> Document the `Authorization` header. Uses the static `headerWithName` method on - `org.springframework.restdocs.headers.HeaderDocumentation`. -<4> Produce a snippet describing the response's headers. Uses the static `responseHeaders` - method on `org.springframework.restdocs.headers.HeaderDocumentation`. +`org.springframework.restdocs.headers.HeaderDocumentation`. +<4> Produce a snippet describing the response's headers. Uses the static +`responseHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`. The result is a snippet named `request-headers.adoc` and a snippet named `response-headers.adoc`. Each contains a table describing the headers. @@ -954,7 +956,7 @@ following examples show how to do so: include::{examples-dir}/com/example/mockmvc/MockMvcSnippetReuse.java[tags=use] ---- <1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific - to the resource that is being documented. +to the resource that is being documented. [source,java,indent=0,role="secondary"] .WebTestClient @@ -983,7 +985,7 @@ 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. +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`] diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index 95cdee56..f6b7c15b 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -117,14 +117,14 @@ the configuration are described in the following listings: ---- <1> Add a dependency on `spring-restdocs-mockmvc` in the `test` scope. If you want to use - `WebTestClient` add a dependency on `spring-restdocs-webtestclient` instead. +`WebTestClient` add a dependency on `spring-restdocs-webtestclient` instead. <2> Add the Asciidoctor plugin. <3> Using `prepare-package` allows the documentation to be - <>. +<>. <4> Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin. This - will automatically configure the `snippets` attribute for use in your `.adoc` files to - point to `target/generated-snippets`. It will also allow you to use the `operation` - block macro. +will automatically configure the `snippets` attribute for use in your `.adoc` files to +point to `target/generated-snippets`. It will also allow you to use the `operation` block +macro. [source,indent=0,subs="verbatim,attributes",role="secondary"] .Gradle @@ -153,11 +153,12 @@ the configuration are described in the following listings: ---- <1> Apply the Asciidoctor plugin. <2> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctor` configuration. - This will automatically configure the `snippets` attribute for use in your `.adoc` - files to point to `build/generated-snippets`. It will also allow you to use the - `operation` block macro. -<3> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` configuration. If - you want to use `WebTestClient`, add a dependency on `spring-restdocs-webtestclient` instead. +This will automatically configure the `snippets` attribute for use in your `.adoc` files +to point to `build/generated-snippets`. It will also allow you to use the `operation` +block macro. +<3> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` +configuration. If you want to use `WebTestClient`, add a dependency on +`spring-restdocs-webtestclient` instead. <4> Configure a property to define the output location for generated snippets. <5> Configure the `test` task to add the snippets directory as an output. <6> Configure the `asciidoctor` task diff --git a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc index 05ba07bb..f8e18fbe 100644 --- a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc +++ b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc @@ -173,7 +173,7 @@ the following example shows, you can specify the widths of a table's columns by \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. +times as wide as the first. ====