Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch '2.0.x'

Browse Source 
# Conflicts:
#	docs/src/docs/asciidoc/documenting-your-api.adoc
#	docs/src/docs/asciidoc/getting-started.adoc
This commit is contained in:
Andy Wilkinson
2022-01-10 11:29:52 +00:00
parent 5dd1bd4beb 96293c0f17
commit 7428164204
3 changed files with 78 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/src/docs/asciidoc/documenting-your-api.adoc
View File

@@ -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`]

21
docs/src/docs/asciidoc/getting-started.adoc
View File

@@ -117,14 +117,14 @@ the configuration are described in the following listings:
</build>
----
<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
<<getting-started-build-configuration-packaging-the-documentation, included in the package>>.
<<getting-started-build-configuration-packaging-the-documentation, included in the package>>.
<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

2
docs/src/docs/asciidoc/working-with-asciidoctor.adoc
View File

@@ -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.
====