diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2089a94..34627e39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,47 +1,38 @@ # Contributing to Spring REST Docs -Spring REST Docs is released under the Apache 2.0 license. If you would like to -contribute something, or simply want to work with the code, this document should help you -to get started. +Spring REST Docs is released under the Apache 2.0 license. +If you would like to contribute something, or simply want to work with the code, this document should help you to get started. ## Code of conduct -This project adheres to the Contributor Covenant [code of conduct][1]. By participating, -you are expected to uphold this code. Please report unacceptable behavior to -spring-code-of-conduct@pivotal.io. +This project adheres to the Contributor Covenant [code of conduct][1]. By participating, you are expected to uphold this code. +Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. ## Sign the contributor license agreement -Before we accept a non-trivial patch or pull request we will need you to sign the -[contributor's license agreement (CLA)][2]. Signing the contributor's agreement does not -grant anyone commit rights to the main repository, but it does mean that we can accept -your contributions, and you will get an author credit if we do. +Before we accept a non-trivial patch or pull request we will need you to sign the [contributor's license agreement (CLA)][2]. +Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. ## Code conventions and housekeeping None of these is essential for a pull request, but they will all help -- Make sure all new `.java` files to have a simple Javadoc class comment with at least an - `@author` tag identifying you, and preferably at least a paragraph on what the class is - for. -- Add the ASF license header comment to all new `.java` files (copy from existing files - in the project) -- Add yourself as an `@author` to the .java files that you modify substantially (more - than cosmetic changes). +- Make sure all new `.java` files to have a simple Javadoc class comment with at least an `@author` tag identifying you, and preferably at least a paragraph on what the class is for +- Add the ASF license header comment to all new `.java` files (copy from existing files in the project) +- Add yourself as an `@author` to the .java files that you modify substantially (more than cosmetic changes) - Add some Javadocs - Add unit tests that covers and new or modified functionality -- Whenever possible, please rebase your branch against the current main (or other - target branch in the project). -* When writing a commit message please follow [these conventions][3]. Also, if you are - fixing an existing issue please add `Fixes gh-nnn` at the end of the commit message - (where nnn is the issue number). +- Whenever possible, please rebase your branch against the current main (or other target branch in the project) +- When writing a commit message please follow [these conventions][3] + Also, if you are fixing an existing issue please add `Fixes gh-nnn` at the end of the commit message (where nnn is the issue number) ## Working with the code ### Building from source -To build the source you will need Java 8 or later. The code is built with Gradle: +To build the source you will need Java 8 or later. +The code is built with Gradle: ``` $ ./gradlew build @@ -55,15 +46,14 @@ $ ./gradlew buildSamples ### Importing into Eclipse -The project has Gradle's Eclipse plugin applied. Eclipse project and classpath metadata -can be generated by running the `eclipse` task: +The project has Gradle's Eclipse plugin applied. +Eclipse project and classpath metadata can be generated by running the `eclipse` task: ``` $ ./gradlew eclipse ``` -The project can then be imported into Eclipse using `File -> Import…` and then selecting -`General -> Existing Projects into Workspace`. +The project can then be imported into Eclipse using `File -> Import…` and then selecting `General -> Existing Projects into Workspace`. [1]: CODE_OF_CONDUCT.md [2]: https://cla.pivotal.io/sign/spring diff --git a/README.md b/README.md index f7f4087b..a29c5891 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,11 @@ ## Overview -The primary goal of this project is to make it easy to document RESTful services by -combining content that's been hand-written using [Asciidoctor][3] with auto-generated -examples produced with the [Spring MVC Test][4] framework. The result is intended to be -an easy-to-read user guide, akin to [GitHub's API documentation][5] for example, rather -than the fully automated, dense API documentation produced by tools like [Swagger][6]. +The primary goal of this project is to make it easy to document RESTful services by combining content that's been hand-written using [Asciidoctor][3] with auto-generated examples produced with the [Spring MVC Test][4] framework. +The result is intended to be an easy-to-read user guide, akin to [GitHub's API documentation][5] for example, rather than the fully automated, dense API documentation produced by tools like [Swagger][6]. -For a broader introduction see the Documenting RESTful APIs presentation. Both the -[slides][7] and a [video recording][8] are available. +For a broader introduction see the Documenting RESTful APIs presentation. +Both the [slides][7] and a [video recording][8] are available. ## Learning more @@ -17,7 +14,8 @@ To learn more about Spring REST Docs, please consult the [reference documentatio ## Building from source -You will need Java 8 or later to build Spring REST Docs. It is built using [Gradle][10]: +You will need Java 8 or later to build Spring REST Docs. +It is built using [Gradle][10]: ``` ./gradlew build @@ -29,9 +27,9 @@ Contributors to this project agree to uphold its [code of conduct][11]. There are several that you can contribute to Spring REST Docs: - - Open a [pull request][12]. Please see the [contributor guidelines][13] for details. - - Ask and answer questions on Stack Overflow using the [`spring-restdocs`][15] tag. - - Chat with fellow users [on Gitter][16]. + - Open a [pull request][12]. Please see the [contributor guidelines][13] for details + - Ask and answer questions on Stack Overflow using the [`spring-restdocs`][15] tag + - Chat with fellow users [on Gitter][16] ## Third-party extensions diff --git a/docs/src/docs/asciidoc/configuration.adoc b/docs/src/docs/asciidoc/configuration.adoc index 6c6bd193..b4fdc475 100644 --- a/docs/src/docs/asciidoc/configuration.adoc +++ b/docs/src/docs/asciidoc/configuration.adoc @@ -11,8 +11,7 @@ This section covers configuring documented URIs. [[configuration-uris-mockmvc]] ==== MockMvc URI Customization -When using MockMvc, the default configuration for URIs documented by Spring REST Docs is -as follows: +When using MockMvc, the default configuration for URIs documented by Spring REST Docs is as follows: |=== |Setting |Default @@ -27,9 +26,9 @@ as follows: |`8080` |=== -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: +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] @@ -38,33 +37,27 @@ include::{examples-dir}/com/example/mockmvc/CustomUriConfiguration.java[tags=cus ---- ==== -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. +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. -TIP: To configure a request's context path, use the `contextPath` method on -`MockHttpServletRequestBuilder`. +TIP: To configure a request's context path, use the `contextPath` method on `MockHttpServletRequestBuilder`. [[configuration-uris-rest-assured]] ==== REST Assured URI Customization -REST Assured tests a service by making actual HTTP requests. As a result, URIs must be -customized once the operation on the service has been performed but before it is -documented. A -<> is provided for this purpose. +REST Assured tests a service by making actual HTTP requests. +As a result, URIs must be customized once the operation on the service has been performed but before it is documented. +A <> is provided for this purpose. [[configuration-uris-webtestclient]] ==== WebTestClient URI Customization -When using WebTestClient, the default base for URIs documented by Spring REST -Docs is `http://localhost:8080`. 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: +When using WebTestClient, the default base for URIs documented by Spring REST Docs is `http://localhost:8080`. +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] @@ -79,9 +72,9 @@ include::{examples-dir}/com/example/webtestclient/CustomUriConfiguration.java[ta [[configuration-snippet-encoding]] === Snippet Encoding -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`: +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"] @@ -103,18 +96,18 @@ include::{examples-dir}/com/example/restassured/CustomEncoding.java[tags=custom- ---- ==== -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. You can configure the JVM's default -`Charset` byusing the `file.encoding` system property. +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. +You can configure the JVM's default `Charset` by using the `file.encoding` system property. [[configuration-snippet-template-format]] === Snippet Template Format -The default snippet template format is Asciidoctor. Markdown is also supported out of the -box. You can change the default format by using the `RestDocumentationConfigurer` API. +The default snippet template format is Asciidoctor. +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: ==== @@ -151,9 +144,8 @@ Six snippets are produced by default: * `request-body` * `response-body` -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: +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"] @@ -178,9 +170,8 @@ include::{examples-dir}/com/example/restassured/CustomDefaultSnippets.java[tags= [[configuration-default-preprocessors]] === Default Operation Preprocessors -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: +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"] diff --git a/docs/src/docs/asciidoc/contributing.adoc b/docs/src/docs/asciidoc/contributing.adoc index abe42773..dd8fd238 100644 --- a/docs/src/docs/asciidoc/contributing.adoc +++ b/docs/src/docs/asciidoc/contributing.adoc @@ -1,37 +1,31 @@ [[contributing]] == Contributing -Spring REST Docs is intended to make it easy for you to produce high-quality -documentation for your RESTful services. However, we cannot achieve that goal without -your contributions. +Spring REST Docs is intended to make it easy for you to produce high-quality documentation for your RESTful services. +However, we cannot achieve that goal without your contributions. [[contributing-questions]] === Questions -You can ask questions about Spring REST Docs on https://stackoverflow.com[Stack Overflow] -by using the `spring-restdocs` tag. Similarly, we encourage you to help your fellow -Spring REST Docs users by answering questions. +You can ask questions about Spring REST Docs on https://stackoverflow.com[Stack Overflow] by using the `spring-restdocs` tag. +Similarly, we encourage you to help your fellow Spring REST Docs users by answering questions. [[contributing-bugs]] === Bugs -If you believe you have found a bug, please take a moment to search the -{github}/issues?q=is%3Aissue[existing issues]. If no one else has reported the problem, -please {github}/issues/new[open a new issue] that describes the problem in detail and, -ideally, includes a test that reproduces it. +If you believe you have found a bug, please take a moment to search the {github}/issues?q=is%3Aissue[existing issues]. +If no one else has reported the problem, please {github}/issues/new[open a new issue] that describes the problem in detail and, ideally, includes a test that reproduces it. [[contributing-enhancements]] === Enhancements -If you would like an enhancement to be made to Spring REST Docs, pull requests are most -welcome. 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 proprosed. You may also want to -{github}/issues/new[open a new issue] to discuss a possible enhancement before work on it -begins. +If you would like an enhancement to be made to Spring REST Docs, pull requests are most welcome. +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. diff --git a/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc b/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc index 84f1268a..4e6d3b8b 100644 --- a/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc +++ b/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc @@ -1,14 +1,12 @@ [[customizing-requests-and-responses]] == Customizing requests and responses -There may be situations where you do not want to document a request exactly as it was sent -or a response exactly as it was received. Spring REST Docs provides a number of -preprocessors that can be used to modify a request or response before it is documented. +There may be situations where you do not want to document a request exactly as it was sent or a response exactly as it was received. +Spring REST Docs provides a number of preprocessors that can be used to modify a request or response before it is documented. -Preprocessing is configured by calling `document` with an `OperationRequestPreprocessor` -or an `OperationResponsePreprocessor`. You can obtain instances by using the static -`preprocessRequest` and `preprocessResponse` methods on `Preprocessors`. The following -examples show how to do so: +Preprocessing is configured by calling `document` with an `OperationRequestPreprocessor` or an `OperationResponsePreprocessor`. +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"] @@ -36,10 +34,9 @@ include::{examples-dir}/com/example/restassured/PerTestPreprocessing.java[tags=p <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): +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"] @@ -67,8 +64,8 @@ include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags <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: +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"] @@ -90,8 +87,8 @@ include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags ---- ==== -Various built-in preprocessors, including those illustrated above, are available through -the static methods on `Preprocessors`. See <> for further details. +Various built-in preprocessors, including those illustrated above, are available through the static methods on `Preprocessors`. +See <> for further details. @@ -103,70 +100,58 @@ the static methods on `Preprocessors`. See <> for further [[customizing-requests-and-responses-preprocessors-pretty-print]] ==== Pretty Printing -`prettyPrint` on `Preprocessors` formats the content of the request or response -to make it easier to read. +`prettyPrint` on `Preprocessors` formats the content of the request or response to make it easier to read. [[customizing-requests-and-responses-preprocessors-mask-links]] ==== Masking Links -If you are documenting a hypermedia-based API, you may want to encourage clients to -navigate the API by using links rather than through the use of hard coded URIs. One way to -do so is to limit the use of URIs in the documentation. `maskLinks` on -`Preprocessors` replaces the `href` of any links in the response with `...`. You can also -specify a different replacement if you wish. +If you are documenting a hypermedia-based API, you may want to encourage clients to navigate the API by using links rather than through the use of hard coded URIs. +One way to do so is to limit the use of URIs in the documentation. +`maskLinks` on `Preprocessors` replaces the `href` of any links in the response with `...`. +You can also specify a different replacement if you wish. [[customizing-requests-and-responses-preprocessors-remove-headers]] ==== Removing Headers -`removeHeaders` on `Preprocessors` removes any headers from the request or response where -the name is equal to any of the given header names. +`removeHeaders` on `Preprocessors` removes any headers from the request or response where the name is equal to any of the given header names. -`removeMatchingHeaders` on `Preprocessors` removes any headers from the request or -response where the name matches any of the given regular expression patterns. +`removeMatchingHeaders` on `Preprocessors` removes any headers from the request or response where the name matches any of the given regular expression patterns. [[customizing-requests-and-responses-preprocessors-replace-patterns]] ==== Replacing Patterns -`replacePattern` on `Preprocessors` provides a general purpose mechanism for -replacing content in a request or response. Any occurrences that match a regular -expression are replaced. +`replacePattern` on `Preprocessors` provides a general purpose mechanism for replacing content in a request or response. +Any occurrences that match a regular expression are replaced. [[customizing-requests-and-responses-preprocessors-modify-request-parameters]] ==== Modifying Request Parameters -You can use `modifyParameters` on `Preprocessors` to add, set, and remove request -parameters. +You can use `modifyParameters` on `Preprocessors` to add, set, and remove request parameters. [[customizing-requests-and-responses-preprocessors-modify-uris]] ==== Modifying URIs -TIP: If you use MockMvc or a WebTestClient that is not bound to a server, -you should customize URIs by <>. +TIP: If you use MockMvc or a WebTestClient that is not bound to a server, you should customize URIs by <>. -You can use `modifyUris` on `Preprocessors` to modify any URIs in a request -or a response. When using REST Assured or WebTestClient bound to a server, this -lets you customize the URIs that appear in the documentation while testing a -local instance of the service. +You can use `modifyUris` on `Preprocessors` to modify any URIs in a request or a response. +When using REST Assured or WebTestClient bound to a server, this lets you customize the URIs that appear in the documentation while testing a local instance of the service. [[customizing-requests-and-responses-preprocessors-writing-your-own]] ==== Writing Your Own Preprocessor -If one of the built-in preprocessors does not meet your needs, you can write your own by -implementing the `OperationPreprocessor` interface. You can then use your custom -preprocessor in exactly the same way as any of the built-in preprocessors. +If one of the built-in preprocessors does not meet your needs, you can write your own by implementing the `OperationPreprocessor` interface. +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`. +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`. diff --git a/docs/src/docs/asciidoc/documenting-your-api.adoc b/docs/src/docs/asciidoc/documenting-your-api.adoc index cadd5488..80283ed3 100644 --- a/docs/src/docs/asciidoc/documenting-your-api.adoc +++ b/docs/src/docs/asciidoc/documenting-your-api.adoc @@ -8,8 +8,7 @@ This section provides more details about using Spring REST Docs to document your [[documenting-your-api-hypermedia]] === Hypermedia -Spring REST Docs provides support for documenting the links in a -https://en.wikipedia.org/wiki/HATEOAS[hypermedia-based] API. +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: ==== @@ -19,10 +18,9 @@ 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`. -<2> Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` 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`. <3> Expect a link whose `rel` is `bravo`. [source,java,indent=0,role="secondary"] @@ -31,10 +29,9 @@ Uses the static `links` method on 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`. -<2> Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` 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`. <3> Expect a link whose `rel` is `bravo`. [source,java,indent=0,role="secondary"] @@ -43,31 +40,26 @@ Uses the static `links` method on include::{examples-dir}/com/example/restassured/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`. -<2> Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` 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`. <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. +The result is a snippet named `links.adoc` that contains a table describing the resource's links. -TIP: If a link in the response has a `title`, you can omit the description from its -descriptor and the `title` is used. If you omit the description and the link does -not have a `title`, a failure occurs. +TIP: If a link in the response has a `title`, you can omit the description from its descriptor and the `title` is used. +If you omit the description and the link does not have a `title`, a failure occurs. -When documenting links, the test fails if an undocumented link is found in the -response. Similarly, the test also fails if a documented link is not found in the -response and the link has not been marked as optional. +When documenting links, the test fails if an undocumented link is found in the response. +Similarly, the test also fails if a documented link is not found in the response and the link has not been marked as optional. -If you do not want to document a link, you can mark it as ignored. Doing so prevents it -from appearing in the generated snippet while avoiding the failure described above. +If you do not want to document a link, you can mark it as ignored. +Doing so prevents it from appearing in the generated snippet while avoiding the failure described above. -You can also document links in a relaxed mode, where any undocumented links do not cause -a test failure. To do so, use the `relaxedLinks` method on -`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. This can be useful when -documenting a particular scenario where you only want to focus on a subset of the links. +You can also document links in a relaxed mode, where any undocumented links do not cause a test failure. +To do so, use the `relaxedLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +This can be useful when documenting a particular scenario where you only want to focus on a subset of the links. @@ -76,14 +68,13 @@ documenting a particular scenario where you only want to focus on a subset of th Two link formats are understood by default: -* Atom: Links are expected to be in an array named `links`. This is used by default when - the content type of the response is compatible with `application/json`. -* HAL: Links are expected to be in a map named `_links`. This is used by default when the - content type of the response is compatible with `application/hal+json`. +* Atom: Links are expected to be in an array named `links`. + This is used by default when the content type of the response is compatible with `application/json`. +* HAL: Links are expected to be in a map named `_links`. + This is used by default when the content type of the response is compatible with `application/hal+json`. -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: +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"] @@ -91,41 +82,36 @@ show how to do so: ---- include::{examples-dir}/com/example/mockmvc/Hypermedia.java[tag=explicit-extractor] ---- -<1> Indicate that the links are in HAL format. Uses the static `halLinks` method on -`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +<1> Indicate that the links are in HAL format. +Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/Hypermedia.java[tag=explicit-extractor] ---- -<1> Indicate that the links are in HAL format. Uses the static `halLinks` method on -`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +<1> Indicate that the links are in HAL format. +Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/Hypermedia.java[tag=explicit-extractor] ---- -<1> Indicate that the links are in HAL format. Uses the static `halLinks` method on -`org.springframework.restdocs.hypermedia.HypermediaDocumentation`. +<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. +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. [[documenting-your-api-hypermedia-ignoring-common-links]] ==== Ignoring Common Links -Rather than documenting links that are common to every response, such as `self` and -`curies` when using HAL, you may want to document them once in an overview section and -then ignore them in the rest of your API's documentation. To do so, you can build on the -<> to add link -descriptors to a snippet that is preconfigured to ignore certain links. The following -example shows how to do so: +Rather than documenting links that are common to every response, such as `self` and `curies` when using HAL, you may want to document them once in an overview section and then ignore them in the rest of your API's documentation. +To do so, you can build on the <> 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] @@ -139,21 +125,17 @@ include::{examples-dir}/com/example/Hypermedia.java[tags=ignore-links] [[documenting-your-api-request-response-payloads]] === Request and Response Payloads -In addition to the hypermedia-specific support <>, support for general documentation of request and response payloads is also -provided. +In addition to the hypermedia-specific support <>, support for general documentation of request and response payloads is also provided. -By default, Spring REST Docs automatically generates snippets for the body of the request -and the body of the response. These snippets are named `request-body.adoc` and -`response-body.adoc` respectively. +By default, Spring REST Docs automatically generates snippets for the body of the request and the body of the response. +These snippets are named `request-body.adoc` and `response-body.adoc` respectively. [[documenting-your-api-request-response-payloads-fields]] ==== Request and Response Fields -To provide more detailed documentation of a request or response payload, support for -documenting the payload's fields is provided. +To provide more detailed documentation of a request or response payload, support for documenting the payload's fields is provided. Consider the following payload: @@ -177,11 +159,11 @@ 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`. -<2> Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method -on `org.springframework.restdocs.payload.PayloadDocumentation`. +<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`. +<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`. [source,java,indent=0,role="secondary"] @@ -189,11 +171,11 @@ on `org.springframework.restdocs.payload.PayloadDocumentation`. ---- 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`. -<2> Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method -on `org.springframework.restdocs.payload.PayloadDocumentation`. +<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`. +<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`. [source,java,indent=0,role="secondary"] @@ -201,24 +183,23 @@ on `org.springframework.restdocs.payload.PayloadDocumentation`. ---- include::{examples-dir}/com/example/restassured/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`. -<2> Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method -on `org.springframework.restdocs.payload.PayloadDocumentation`. +<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`. +<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`. For responses, this snippet is named -`response-fields.adoc`. +The result is a snippet that contains a table describing the fields. +For requests, this snippet is named `request-fields.adoc`. +For responses, this snippet is named `response-fields.adoc`. When documenting fields, the test fails if an undocumented field is found in the payload. -Similarly, the test also fails if a documented field is not found in the payload and the -field has not been marked as optional. +Similarly, the test also fails if a documented field is not found in the payload and the field has not been marked as optional. -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: +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"] @@ -226,46 +207,42 @@ 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`. +<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`. [source,java,indent=0,role="secondary"] .WebTestClient ---- 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`. +<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`. [source,java,indent=0,role="secondary"] .REST Assured ---- 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`. +<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. See <>. +`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. +See <>. If you do not want to document a field or subsection at all, you can mark it as ignored. -This prevents it from appearing in the generated snippet while avoiding the failure -described earlier. +This prevents it from appearing in the generated snippet while avoiding the failure described earlier. -You can also document fields in a relaxed mode, where any undocumented fields do not -cause a test failure. To do so, use the `relaxedRequestFields` and `relaxedResponseFields` -methods on -`org.springframework.restdocs.payload.PayloadDocumentation`. This can be useful when -documenting a particular scenario where you want to focus only on a subset of the payload. +You can also document fields in a relaxed mode, where any undocumented fields do not cause a test failure. +To do so, use the `relaxedRequestFields` and `relaxedResponseFields` methods on `org.springframework.restdocs.payload.PayloadDocumentation`. +This can be useful when documenting a particular scenario where you want to focus only on a subset of the payload. 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`. +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 @@ -275,12 +252,12 @@ This section describes how to work with fields in JSON payloads. [[documenting-your-api-request-response-payloads-fields-json-field-paths]] ====== JSON Field Paths -JSON field paths use either dot notation or bracket notation. Dot notation uses '.' to -separate each key in the path (for example, `a.b`). Bracket notation wraps each key in -square brackets and single quotation marks (for example, `['a']['b']`). In either case, -`[]` is used to identify an array. Dot notation is more concise, but using bracket -notation enables the use of `.` within a key name (for example, `['a.b']`). The two -different notations can be used in the same path (for example, `a['b']`). +JSON field paths use either dot notation or bracket notation. +Dot notation uses '.' to separate each key in the path (for example, `a.b`). +Bracket notation wraps each key in square brackets and single quotation marks (for example, `['a']['b']`). +In either case, `[]` is used to identify an array. +Dot notation is more concise, but using bracket notation enables the use of `.` within a key name (for example, `['a.b']`). +The two different notations can be used in the same path (for example, `a['b']`). Consider the following JSON payload: @@ -344,10 +321,10 @@ In the preceding JSON payload, the following paths are all present: |=== -You can also document a payload that uses an array at its root. 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: +You can also document a payload that uses an array at its root. +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] @@ -363,8 +340,8 @@ found in the following array: ---- ==== -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: +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] @@ -385,8 +362,8 @@ You can use `\*` as a wildcard to match fields with different names. For example [[documenting-your-api-request-response-payloads-fields-json-field-types]] ====== JSON Field Types -When a field is documented, Spring REST Docs tries to determine its type by examining the -payload. Seven different types are supported: +When a field is documented, Spring REST Docs tries to determine its type by examining the payload. +Seven different types are supported: [cols="1,3"] |=== @@ -414,9 +391,9 @@ payload. Seven different types are supported: | The field occurs multiple times in the payload with a variety of different types. |=== -You can also explicitly set the type by using the `type(Object)` method on -`FieldDescriptor`. The result of the `toString` method of the supplied `Object` is used -in the documentation. Typically, one of the values enumerated by `JsonFieldType` is used. +You can also explicitly set the type by using the `type(Object)` method on `FieldDescriptor`. +The result of the `toString` method of the supplied `Object` is used in the documentation. +Typically, one of the values enumerated by `JsonFieldType` is used. The following examples show how to do so: ==== @@ -451,26 +428,24 @@ This section describes how to work with XML payloads. [[documenting-your-api-request-response-payloads-fields-xml-field-paths]] ====== XML Field Paths -XML field paths are described using XPath. `/` is used to descend into a child node. +XML field paths are described using XPath. +`/` is used to descend into a child node. [[documenting-your-api-request-response-payloads-fields-xml-field-types]] ====== XML Field Types -When documenting an XML payload, you must provide a type for the field by using the -`type(Object)` method on `FieldDescriptor`. The result of the supplied type's `toString` -method is used in the documentation. +When documenting an XML payload, you must provide a type for the field by using the `type(Object)` method on `FieldDescriptor`. +The result of the supplied type's `toString` method is used in the documentation. [[documenting-your-api-request-response-payloads-fields-reusing-field-descriptors]] ===== Reusing Field Descriptors -In addition to the general support for <>, the request and response snippets let additional descriptors be configured -with a path prefix. This lets the descriptors for a repeated portion of a request or -response payload be created once and then reused. +In addition to the general support for <>, the request and response snippets let additional descriptors be configured with a path prefix. +This lets the descriptors for a repeated portion of a request or response payload be created once and then reused. Consider an endpoint that returns a book: @@ -502,9 +477,8 @@ Now consider an endpoint that returns an array of books: ---- ==== -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. +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: @@ -549,8 +523,7 @@ You can also use the descriptors to document an array of books, as follows: 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 -`[].` +<2> Document `[].title` and `[].author` by using the existing descriptors prefixed with `[].` [source,java,indent=0,role="secondary"] .WebTestClient @@ -558,8 +531,7 @@ include::{examples-dir}/com/example/mockmvc/Payload.java[tags=book-array] 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 -`[].` +<2> Document `[].title` and `[].author` by using the existing descriptors prefixed with `[].` [source,java,indent=0,role="secondary"] .REST Assured @@ -567,16 +539,14 @@ include::{examples-dir}/com/example/webtestclient/Payload.java[tags=book-array] 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 -`[].` +<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 -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. +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 @@ -609,30 +579,27 @@ 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`. +<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`. [source,java,indent=0,role="secondary"] .WebTestClient ---- 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`. +<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`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/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`. +<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: @@ -649,10 +616,10 @@ 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 customized the -identifier by using the `withSubsectionId(String)` method, as follows: +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] @@ -668,9 +635,8 @@ The result is a snippet named `request-body-temp.adoc`. [[documenting-your-api-request-response-payloads-subsections-fields]] ===== Documenting the Fields of a Subsection of a Request or Response -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: +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"] @@ -678,9 +644,8 @@ fields of the `temperature` object (`high` and `low`) as follows: ---- include::{examples-dir}/com/example/mockmvc/Payload.java[tags=fields-subsection] ---- -<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`. +<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. [source,java,indent=0,role="secondary"] @@ -688,9 +653,8 @@ include::{examples-dir}/com/example/mockmvc/Payload.java[tags=fields-subsection] ---- include::{examples-dir}/com/example/webtestclient/Payload.java[tags=fields-subsection] ---- -<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`. +<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. [source,java,indent=0,role="secondary"] @@ -698,26 +662,24 @@ include::{examples-dir}/com/example/webtestclient/Payload.java[tags=fields-subse ---- include::{examples-dir}/com/example/restassured/Payload.java[tags=fields-subsection] ---- -<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`. +<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. By default, this identifier is `beneath-${path}`. For example, -the preceding code results in a snippet named -`response-fields-beneath-weather.temperature.adoc`. +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. +By default, this identifier is `beneath-${path}`. +For example, the preceding code results in a snippet named `response-fields-beneath-weather.temperature.adoc`. [[documenting-your-api-request-parameters]] === Request Parameters -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: +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"] @@ -725,13 +687,11 @@ 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. +<1> Perform a `GET` request with two parameters, `page` and `per_page`, in the query 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`. -<3> Document the `page` parameter. Uses the static `parameterWithName` 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`. <4> Document the `per_page` parameter. [source,java,indent=0,role="secondary"] @@ -739,13 +699,11 @@ Uses the static `requestParameters` method on ---- 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. +<1> Perform a `GET` request with two parameters, `page` and `per_page`, in the query 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`. -<3> Document the `page` parameter. Uses the static `parameterWithName` 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`. <4> Document the `per_page` parameter. [source,java,indent=0,role="secondary"] @@ -754,17 +712,15 @@ Uses the static `requestParameters` method on include::{examples-dir}/com/example/restassured/RequestParameters.java[tags=request-parameters-query-string] ---- <1> Configure Spring REST Docs to produce a snippet describing the request's parameters. -Uses the static `requestParameters` method on -`org.springframework.restdocs.request.RequestDocumentation`. -<2> Document the `page` parameter. Uses the static `parameterWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +Uses the static `requestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`. +<2> Document the `page` parameter. +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. +<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: +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"] @@ -790,30 +746,25 @@ include::{examples-dir}/com/example/restassured/RequestParameters.java[tags=requ <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. +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. -When documenting request parameters, the test fails if an undocumented request parameter -is used in the request. Similarly, the test also fails if a documented request parameter -is not found in the request and the request parameter has not been marked as optional. +When documenting request parameters, the test fails if an undocumented request parameter is used in the request. +Similarly, the test also fails if a documented request parameter is not found in the request and the request parameter has not been marked as optional. -If you do not want to document a request parameter, you can mark it as ignored. This -prevents it from appearing in the generated snippet while avoiding the failure described -above. +If you do not want to document a request parameter, you can mark it as ignored. +This prevents it from appearing in the generated snippet while avoiding the failure described above. -You can also document request parameters in a relaxed mode where any undocumented -parameters do not cause a test failure. To do so, use the `relaxedRequestParameters` -method on `org.springframework.restdocs.request.RequestDocumentation`. This can be useful -when documenting a particular scenario where you only want to focus on a subset of the -request parameters. +You can also document request parameters in a relaxed mode where any undocumented parameters do not cause a test failure. +To do so, use the `relaxedRequestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`. +This can be useful when documenting a particular scenario where you only want to focus on a subset of the request parameters. [[documenting-your-api-path-parameters]] === Path Parameters -You can document a request's path parameters by using `pathParameters`. The following -examples show how to do so: +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"] @@ -822,11 +773,10 @@ examples show how to do so: include::{examples-dir}/com/example/mockmvc/PathParameters.java[tags=path-parameters] ---- <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`. -<3> Document the parameter named `latitude`. Uses the static `parameterWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +<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`. +<3> Document the parameter named `latitude`. +Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`. <4> Document the parameter named `longitude`. [source,java,indent=0,role="secondary"] @@ -835,11 +785,10 @@ parameters. Uses the static `pathParameters` method on include::{examples-dir}/com/example/webtestclient/PathParameters.java[tags=path-parameters] ---- <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`. -<3> Document the parameter named `latitude`. Uses the static `parameterWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +<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`. +<3> Document the parameter named `latitude`. +Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`. <4> Document the parameter named `longitude`. [source,java,indent=0,role="secondary"] @@ -847,43 +796,35 @@ parameters. Uses the static `pathParameters` method on ---- include::{examples-dir}/com/example/restassured/PathParameters.java[tags=path-parameters] ---- -<1> 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`. -<2> Document the parameter named `latitude`. Uses the static `parameterWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +<1> 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`. +<2> Document the parameter named `latitude`. +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. +The result is a snippet named `path-parameters.adoc` that contains a table describing the path parameters that are supported by the resource. -TIP: If you use MockMvc, to make the path parameters available for documentation, -you must build the request by using one of the methods on -`RestDocumentationRequestBuilders` rather than `MockMvcRequestBuilders`. +TIP: If you use MockMvc, to make the path parameters available for documentation, you must build the request by using one of the methods on `RestDocumentationRequestBuilders` rather than `MockMvcRequestBuilders`. -When documenting path parameters, the test fails if an undocumented path parameter is -used in the request. Similarly, the test also fails if a documented path parameter is not -found in the request and the path parameter has not been marked as optional. +When documenting path parameters, the test fails if an undocumented path parameter is used in the request. +Similarly, the test also fails if a documented path parameter is not found in the request and the path parameter has not been marked as optional. -You can also document path parameters in a relaxed mode, where any undocumented -parameters do not cause a test failure. To do so, use the `relaxedPathParameters` method -on `org.springframework.restdocs.request.RequestDocumentation`. This can be useful when -documenting a particular scenario where you only want to focus on a subset of the path -parameters. +You can also document path parameters in a relaxed mode, where any undocumented parameters do not cause a test failure. +To do so, use the `relaxedPathParameters` method on `org.springframework.restdocs.request.RequestDocumentation`. +This can be useful when documenting a particular scenario where you only want to focus on a subset of the path parameters. -If you do not want to document a path parameter, you can mark it as ignored. Doing so -prevents it from appearing in the generated snippet while avoiding the failure described -earlier. +If you do not want to document a path parameter, you can mark it as ignored. +Doing so prevents it from appearing in the generated snippet while avoiding the failure described earlier. [[documenting-your-api-request-parts]] === Request Parts -You can use `requestParts` to document the parts of a multipart request. The following -example shows how to do so: +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"] @@ -892,11 +833,10 @@ example shows how to do so: 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`. -<3> Document the part named `file`. Uses the static `partWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +<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`. +<3> Document the part named `file`. +Uses the static `partWithName` method on `org.springframework.restdocs.request.RequestDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient @@ -904,49 +844,41 @@ the static `requestParts` method on include::{examples-dir}/com/example/webtestclient/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`. -<3> Document the part named `file`. Uses the static `partWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +<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`. +<3> Document the part named `file`. +Uses the static `partWithName` method on `org.springframework.restdocs.request.RequestDocumentation`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/RequestParts.java[tags=request-parts] ---- -<1> Configure Spring REST Docs to produce a snippet describing the request's parts. Uses -the static `requestParts` method on -`org.springframework.restdocs.request.RequestDocumentation`. -<2> Document the part named `file`. Uses the static `partWithName` method on -`org.springframework.restdocs.request.RequestDocumentation`. +<1> Configure Spring REST Docs to produce a snippet describing the request's parts. +Uses the static `requestParts` method on `org.springframework.restdocs.request.RequestDocumentation`. +<2> Document the part named `file`. +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. +The result is a snippet named `request-parts.adoc` that contains a table describing the request parts that are supported by the resource. -When documenting request parts, the test fails if an undocumented part is used in the -request. Similarly, the test also fails if a documented part is not found in the request -and the part has not been marked as optional. +When documenting request parts, the test fails if an undocumented part is used in the request. +Similarly, the test also fails if a documented part is not found in the request and the part has not been marked as optional. -You can also document request parts in a relaxed mode where any undocumented parts do not -cause a test failure. To do so, use the `relaxedRequestParts` method on -`org.springframework.restdocs.request.RequestDocumentation`. This can be useful -when documenting a particular scenario where you only want to focus on a subset of the -request parts. +You can also document request parts in a relaxed mode where any undocumented parts do not cause a test failure. +To do so, use the `relaxedRequestParts` method on `org.springframework.restdocs.request.RequestDocumentation`. +This can be useful when documenting a particular scenario where you only want to focus on a subset of the request parts. -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. +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 -You can document the payload of a request part in much the same way as the -<>, with support -for documenting a request part's body and its fields. +You can document the payload of a request part in much the same way as the <>, with support for documenting a request part's body and its fields. @@ -961,40 +893,35 @@ You can generate a snippet containing the body of a request part as follows: ---- include::{examples-dir}/com/example/mockmvc/RequestPartPayload.java[tags=body] ---- -<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`. +<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`. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/RequestPartPayload.java[tags=body] ---- -<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`. +<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`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/RequestPartPayload.java[tags=body] ---- -<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`. +<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`. +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`. [[documenting-your-api-request-parts-payloads-fields]] ==== Documenting a Request Part's Fields -You can document a request part's fields in much the same way as the fields of a request -or response, as follows: +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"] @@ -1002,63 +929,54 @@ 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`. -<2> Expect a field with the path `version`. Uses the static `fieldWithPath` method on -`org.springframework.restdocs.payload.PayloadDocumentation`. +<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`. +<2> Expect a field with the path `version`. +Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient ---- 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`. -<2> Expect a field with the path `version`. Uses the static `fieldWithPath` method on -`org.springframework.restdocs.payload.PayloadDocumentation`. +<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`. +<2> Expect a field with the path `version`. +Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/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`. -<2> Expect a field with the path `version`. Uses the static `fieldWithPath` method on -`org.springframework.restdocs.payload.PayloadDocumentation`. +<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`. +<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`. For example, documenting a part named -`metadata` produces a snippet named `request-part-metadata-fields.adoc`. +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 `metadata` produces a snippet named `request-part-metadata-fields.adoc`. -When documenting fields, the test fails if an undocumented field is found in the payload -of the part. Similarly, the test also fails if a documented field is not found in the -payload of the part and the field has not been marked as optional. For payloads with a -hierarchical structure, documenting a field is sufficient for all of its descendants to -also be treated as having been documented. +When documenting fields, the test fails if an undocumented field is found in the payload of the part. +Similarly, the test also fails if a documented field is not found in the payload of the part and the field has not been marked as optional. +For payloads with a hierarchical structure, documenting a field is sufficient for all of its descendants to also be treated as having been documented. -If you do not want to document a field, you can mark it as ignored. Doing so prevents it -from appearing in the generated snippet while avoiding the failure described above. +If you do not want to document a field, you can mark it as ignored. +Doing so prevents it from appearing in the generated snippet while avoiding the failure described above. -You can also document fields in a relaxed mode, where any undocumented fields do not -cause a test failure. To do so, use the `relaxedRequestPartFields` method on -`org.springframework.restdocs.payload.PayloadDocumentation`. This can be useful when -documenting a particular scenario where you only want to focus on a subset of the payload -of the part. +You can also document fields in a relaxed mode, where any undocumented fields do not cause a test failure. +To do so, use the `relaxedRequestPartFields` method on `org.springframework.restdocs.payload.PayloadDocumentation`. +This can be useful when documenting a particular scenario where you only want to focus on a subset of the payload of the part. -For further information on describing fields, documenting payloads that use XML, and -more, see the <>. +For further information on describing fields, documenting payloads that use XML, and more, see the <>. [[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: +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"] @@ -1066,30 +984,26 @@ 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`. -<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`. +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`. [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`. -<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`. +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`. [source,java,indent=0,role="secondary"] .REST Assured @@ -1097,32 +1011,29 @@ Uses the static `requestHeaders` method on include::{examples-dir}/com/example/restassured/HttpHeaders.java[tags=headers] ---- <1> Configure Spring REST Docs to produce a snippet describing the request's headers. -Uses the static `requestHeaders` method on -`org.springframework.restdocs.headers.HeaderDocumentation`. -<2> Document the `Authorization` header. Uses the static `headerWithName` method on -`org.springframework.restdocs.headers.HeaderDocumentation. -<3> Produce a snippet describing the response's headers. Uses the static `responseHeaders` -method on `org.springframework.restdocs.headers.HeaderDocumentation`. +Uses the static `requestHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`. +<2> Document the `Authorization` header. +Uses the static `headerWithName` method on `org.springframework.restdocs.headers.HeaderDocumentation. +<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. +The result is a snippet named `request-headers.adoc` and a snippet named `response-headers.adoc`. +Each contains a table describing the headers. -When documenting HTTP Headers, the test fails if a documented header is not found in -the request or response. +When documenting HTTP Headers, the test fails if a documented header is not found in the request or response. [[documenting-your-api-reusing-snippets]] === Reusing Snippets -It is common for an API that is being documented to have some features that are common -across several of its resources. To avoid repetition when documenting such resources, you -can reuse a `Snippet` configured with the common elements. +It is common for an API that is being documented to have some features that are common across several of its resources. +To avoid repetition when documenting such resources, you can reuse a `Snippet` configured with the common elements. -First, create the `Snippet` that describes the common elements. The following example -shows how to do so: +First, create the `Snippet` that describes the common elements. +The following example shows how to do so: ==== [source,java,indent=0] @@ -1131,8 +1042,8 @@ 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: +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"] @@ -1140,28 +1051,24 @@ 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. +<1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific to the resource that is being documented. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/WebTestClientSnippetReuse.java[tags=use] ---- -<1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific - to the resource that is being documented. +<1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific to the resource that is being documented. [source,java,indent=0,role="secondary"] .REST Assured ---- 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. +<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. +The result of the example is that links with `rel` values of `first`, `last`, `next`, `previous`, `alpha`, and `bravo` are all documented. @@ -1169,8 +1076,8 @@ The result of the example is that links with `rel` values of `first`, `last`, `n === Documenting Constraints Spring REST Docs provides a number of classes that can help you to document constraints. -You can use an instance of `ConstraintDescriptions` to access descriptions of a class's -constraints. The following example shows how to do so: +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] @@ -1178,23 +1085,21 @@ constraints. The following example shows how to do so: 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. +<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. +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. [[documenting-your-api-constraints-finding]] ==== Finding Constraints -By default, constraints are found by using a Bean Validation `Validator`. Currently, only -property constraints are supported. You can customize the `Validator` that is used by -creating `ConstraintDescriptions` with a custom `ValidatorConstraintResolver` instance. -To take complete control of constraint resolution, you can use your own implementation of -`ConstraintResolver`. +By default, constraints are found by using a Bean Validation `Validator`. +Currently, only property constraints are supported. +You can customize the `Validator` that is used by creating `ConstraintDescriptions` with a custom `ValidatorConstraintResolver` instance. +To take complete control of constraint resolution, you can use your own implementation of `ConstraintResolver`. @@ -1245,37 +1150,26 @@ Validator: * `SafeHtml` * `URL` -To override the default descriptions or to provide a new description, you can create a -resource bundle with a base name of -`org.springframework.restdocs.constraints.ConstraintDescriptions`. The Spring -HATEOAS-based sample contains -{samples}/rest-notes-spring-hateoas/src/test/resources/org/springframework/restdocs/constraints/ConstraintDescriptions.properties[an -example of such a resource bundle]. +To override the default descriptions or to provide a new description, you can create a resource bundle with a base name of `org.springframework.restdocs.constraints.ConstraintDescriptions`. +The Spring HATEOAS-based sample contains {samples}/rest-notes-spring-hateoas/src/test/resources/org/springframework/restdocs/constraints/ConstraintDescriptions.properties[an example of such a resource bundle]. -Each key in the resource bundle is the fully-qualified name of a constraint plus a -`.description`. For example, the key for the standard `@NotNull` constraint is -`javax.validation.constraints.NotNull.description`. +Each key in the resource bundle is the fully-qualified name of a constraint plus a `.description`. +For example, the key for the standard `@NotNull` constraint is `javax.validation.constraints.NotNull.description`. -You can use a property placeholder referring to a constraint's attributes in its -description. For example, the default description of the `@Min` constraint, -`Must be at least ${value}`, refers to the constraint's `value` attribute. +You can use a property placeholder referring to a constraint's attributes in its description. +For example, the default description of the `@Min` constraint, `Must be at least ${value}`, refers to the constraint's `value` attribute. -To take more control of constraint description resolution, you can create -`ConstraintDescriptions` with a custom `ResourceBundleConstraintDescriptionResolver`. To -take complete control, you can create `ConstraintDescriptions` with a custom -`ConstraintDescriptionResolver` implementation. +To take more control of constraint description resolution, you can create `ConstraintDescriptions` with a custom `ResourceBundleConstraintDescriptionResolver`. +To take complete control, you can create `ConstraintDescriptions` with a custom `ConstraintDescriptionResolver` implementation. ==== Using Constraint Descriptions in Generated Snippets -Once you have a constraint's descriptions, you are free to use them however you like in -the generated snippets. For example, you may want to include the constraint descriptions -as part of a field's description. Alternatively, you could include the constraints as -<> in -the request fields snippet. The -{samples}/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java[`ApiDocumentation`] -class in the Spring HATEOAS-based sample illustrates the latter approach. +Once you have a constraint's descriptions, you are free to use them however you like in the generated snippets. +For example, you may want to include the constraint descriptions as part of a field's description. +Alternatively, you could include the constraints as <> in the request fields snippet. +The {samples}/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java[`ApiDocumentation`] class in the Spring HATEOAS-based sample illustrates the latter approach. @@ -1297,8 +1191,7 @@ call that is being documented. call that is being documented. | `http-request.adoc` -| Contains the HTTP request that is equivalent to the `MockMvc` call that is being -documented. +| Contains the HTTP request that is equivalent to the `MockMvc` call that is being documented. | `http-response.adoc` | Contains the HTTP response that was returned. @@ -1311,16 +1204,16 @@ documented. |=== -You can configure which snippets are produced by default. See the -<> for more information. +You can configure which snippets are produced by default. +See the <> for more information. [[documentating-your-api-parameterized-output-directories]] === Using Parameterized Output Directories -When using MockMvc, REST Assured, or `WebTestClient` you can parameterize the output directory used by -`document`. Parameterizing output with `WebTestClient` requires Spring Framework 5.3.5 or later. +When using MockMvc, REST Assured, or `WebTestClient` you can parameterize the output directory used by `document`. +Parameterizing output with `WebTestClient` requires Spring Framework 5.3.5 or later. The following parameters are supported: @@ -1350,13 +1243,11 @@ The following parameters are supported: | The count of calls made to the service in the current test. |=== -For example, `document("{class-name}/{method-name}")` in a test method named -`creatingANote` on the test class `GettingStartedDocumentation` writes -snippets into a directory named `getting-started-documentation/creating-a-note`. +For example, `document("{class-name}/{method-name}")` in a test method named `creatingANote` on the test class `GettingStartedDocumentation` writes snippets into a directory named `getting-started-documentation/creating-a-note`. -A parameterized output directory is particularly useful in combination with a `@Before` -method. 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: +A parameterized output directory is particularly useful in combination with a `@Before` method. +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"] @@ -1378,10 +1269,8 @@ include::{examples-dir}/com/example/webtestclient/ParameterizedOutput.java[tags= ---- ==== -With this configuration in place, every call to the service you are testing produces -the <> without any further -configuration. Take a look at the `GettingStartedDocumentation` classes in each of the -sample applications to see this functionality in action. +With this configuration in place, every call to the service you are testing produces the <> without any further configuration. +Take a look at the `GettingStartedDocumentation` classes in each of the sample applications to see this functionality in action. @@ -1392,20 +1281,16 @@ This section describes how to customize the output of Spring REST Docs. [[documenting-your-api-customizing-snippets]] ==== Customizing the Generated Snippets -Spring REST Docs uses https://mustache.github.io[Mustache] templates to produce the -generated snippets. -{source}/spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates[Default -templates] are provided for each of the snippets that Spring REST Docs can produce. To -customize a snippet's content, you can provide your own template. -Templates are loaded from the classpath from an `org.springframework.restdocs.templates` -subpackage. The name of the subpackage is determined by the ID of the template format -that is in use. The default template format, Asciidoctor, has an ID of `asciidoctor`, so -snippets are loaded from `org.springframework.restdocs.templates.asciidoctor`. Each -template is named after the snippet that it produces. For example, to override the -template for the `curl-request.adoc` snippet, create a template named -`curl-request.snippet` in -`src/test/resources/org/springframework/restdocs/templates/asciidoctor`. +Spring REST Docs uses https://mustache.github.io[Mustache] templates to produce the generated snippets. +{source}/spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates[Default templates] are provided for each of the snippets that Spring REST Docs can produce. +To customize a snippet's content, you can provide your own template. + +Templates are loaded from the classpath from an `org.springframework.restdocs.templates` subpackage. +The name of the subpackage is determined by the ID of the template format that is in use. +The default template format, Asciidoctor, has an ID of `asciidoctor`, so snippets are loaded from `org.springframework.restdocs.templates.asciidoctor`. +Each template is named after the snippet that it produces. +For example, to override the template for the `curl-request.adoc` snippet, create a template named `curl-request.snippet` in `src/test/resources/org/springframework/restdocs/templates/asciidoctor`. @@ -1415,17 +1300,15 @@ template for the `curl-request.adoc` snippet, create a template named There are two ways to provide extra information for inclusion in a generated snippet: * Use the `attributes` method on a descriptor to add one or more attributes to it. -* Pass in some attributes when calling `curlRequest`, `httpRequest`, `httpResponse`, and - so on. Such attributes are associated with the snippet as a whole. +* Pass in some attributes when calling `curlRequest`, `httpRequest`, `httpResponse`, and so on. + Such attributes are associated with the snippet as a whole. Any additional attributes are made available during the template rendering process. -Coupled with a custom snippet template, this makes it possible to include extra -information in a generated snippet. +Coupled with a custom snippet template, this makes it possible to include extra information in a generated snippet. -A concrete example is the addition of a constraints column and a title when documenting -request fields. 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: +A concrete example is the addition of a constraints column and a title when documenting request fields. +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"] @@ -1456,9 +1339,8 @@ include::{examples-dir}/com/example/restassured/Payload.java[tags=constraints] <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: +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] diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index 164cc56f..8e914b09 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -17,13 +17,11 @@ If you want to jump straight in, a number of sample applications are available: | {samples}/rest-notes-spring-data-rest[Spring Data REST] | Maven -| Demonstrates the creation of a getting started guide and an API guide for a service - implemented by using https://projects.spring.io/spring-data-rest/[Spring Data REST]. +| Demonstrates the creation of a getting started guide and an API guide for a service implemented by using https://projects.spring.io/spring-data-rest/[Spring Data REST]. | {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]. +| 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]. |=== @@ -84,11 +82,9 @@ Additionally, the `spring-restdocs-restassured` module requires REST Assured 3.0 [[getting-started-build-configuration]] === Build configuration -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: +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"] @@ -131,16 +127,13 @@ 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` or REST Assured rather than MockMvc, add a dependency on -`spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead. +<1> Add a dependency on `spring-restdocs-mockmvc` in the `test` scope. +If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively 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. +<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. [source,indent=0,subs="verbatim,attributes",role="secondary"] .Gradle @@ -174,29 +167,24 @@ macro. ---- <1> Apply the Asciidoctor plugin. <2> Declare the `asciidoctorExt` configuration for dependencies that extend Asciidoctor. -<3> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` -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. -<4> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` -configuration. If you want to use `WebTestClient` or REST Assured rather than MockMvc, -add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` -respectively instead. +<3> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` 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. +<4> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` configuration. +If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead. <5> Configure a property to define the output location for generated snippets. <6> Configure the `test` task to add the snippets directory as an output. <7> Configure the `asciidoctor` task. <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. +<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 -You may want to package the generated documentation in your project's jar file -- for -example, to have it {spring-boot-docs}/#boot-features-spring-mvc-static-content[served as -static content] by Spring Boot. To do so, configure your project's build so that: +You may want to package the generated documentation in your project's jar file -- for example, to have it {spring-boot-docs}/#boot-features-spring-mvc-static-content[served as static content] by Spring Boot. +To do so, configure your project's build so that: 1. The documentation is generated before the jar is built 2. The generated documentation is included in the jar @@ -239,11 +227,8 @@ The following listings show how to do so in both Maven and Gradle: ---- <1> The existing declaration for the Asciidoctor plugin. -<2> The resource plugin must be declared after the Asciidoctor plugin as they are bound -to the same phase (`prepare-package`) and the resource plugin must run after the -Asciidoctor plugin to ensure that the documentation is generated before it's copied. -<3> Copy the generated documentation into the build output's `static/docs` directory, -from where it will be included in the jar file. +<2> The resource plugin must be declared after the Asciidoctor plugin as they are bound to the same phase (`prepare-package`) and the resource plugin must run after the Asciidoctor plugin to ensure that the documentation is generated before it's copied. +<3> Copy the generated documentation into the build output's `static/docs` directory, from where it will be included in the jar file. [source,indent=0,role="secondary"] .Gradle @@ -263,27 +248,23 @@ from where it will be included in the jar file. [[getting-started-documentation-snippets]] === Generating Documentation Snippets -Spring REST Docs uses Spring MVC's -{spring-framework-docs}/testing.html#spring-mvc-test-framework[test framework], -Spring WebFlux's {spring-framework-docs}/testing.html#webtestclient[`WebTestClient`], or -http://rest-assured.io/[REST Assured] to make requests to the service that you are -documenting. It then produces documentation snippets for the request and the resulting -response. + +Spring REST Docs uses Spring MVC's {spring-framework-docs}/testing.html#spring-mvc-test-framework[test framework], Spring WebFlux's {spring-framework-docs}/testing.html#webtestclient[`WebTestClient`], or http://rest-assured.io/[REST Assured] to make requests to the service that you are documenting. +It then produces documentation snippets for the request and the resulting response. [[getting-started-documentation-snippets-setup]] ==== Setting up Your Tests -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. +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`. +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: ==== @@ -294,8 +275,7 @@ public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(); ---- ==== -By default, the `JUnitRestDocumentation` rule is automatically configured with an output -directory based on your project's build tool: +By default, the `JUnitRestDocumentation` rule is automatically configured with an output directory based on your project's build tool: [cols="2,5"] |=== @@ -309,8 +289,7 @@ directory based on your project's build tool: |=== -You can override the default by providing an output directory when you create the -`JUnitRestDocumentation` instance. +You can override the default by providing an output directory when you create the `JUnitRestDocumentation` instance. The following example shows how to do so: ==== @@ -321,8 +300,8 @@ public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("cu ---- ==== -Next, you must provide an `@Before` method to configure MockMvc, WebTestClient or REST -Assured. The following examples show how to do so: +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"] @@ -331,40 +310,34 @@ Assured. The following examples show how to do so: include::{examples-dir}/com/example/mockmvc/ExampleApplicationTests.java[tags=setup] ---- <1> The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`. -You can obtain an instance of this class from the static `documentationConfiguration()` -method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`. +You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/ExampleApplicationTests.java[tags=setup] ---- -<1> The `WebTestClient` instance is configured by adding a -`WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`. You can obtain -an instance of this class from the static `documentationConfiguration()` method on -`org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`. +<1> The `WebTestClient` instance is configured by adding a `WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`. +You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tags=setup] ---- -<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. +<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 <> for more information. +The configurer applies sensible defaults and also provides an API for customizing the configuration. +See the <> for more information. [[getting-started-documentation-snippets-setup-junit-5]] ===== Setting up Your JUnit 5 Tests -When using JUnit 5, the first step in generating documentation snippets is to apply -the `RestDocumentationExtension` to your test class. +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: ==== @@ -385,8 +358,7 @@ public class JUnit5ExampleTests { ---- ==== -The `RestDocumentationExtension` is automatically configured with an output directory -based on your project's build tool: +The `RestDocumentationExtension` is automatically configured with an output directory based on your project's build tool: [cols="2,5"] |=== @@ -400,9 +372,8 @@ based on your project's build tool: |=== -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. The -following example shows how to do so: +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. +The following example shows how to do so: [source,java,indent=0] ---- @@ -414,8 +385,8 @@ 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: +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"] @@ -424,45 +395,40 @@ REST Assured. The following listings show how to do so: include::{examples-dir}/com/example/mockmvc/ExampleApplicationJUnit5Tests.java[tags=setup] ---- <1> The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`. -You can obtain an instance of this class from the static `documentationConfiguration()` -method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`. +You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/ExampleApplicationJUnit5Tests.java[tags=setup] ---- -<1> The `WebTestClient` instance is configured by adding a -`WebTestClientRestDocumentationConfigurer` as an `ExchangeFilterFunction`. You can obtain -an instance of this class from the static `documentationConfiguration()` method on -`org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`. +<1> The `WebTestClient` instance is configured by adding a `WebTestClientRestDocumentationConfigurer` as an `ExchangeFilterFunction`. +You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`. [source,java,indent=0,role="secondary"] .REST Assured ---- include::{examples-dir}/com/example/restassured/ExampleApplicationJUnit5Tests.java[tags=setup] ---- -<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. +<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 <> for more information. +The configurer applies sensible defaults and also provides an API for customizing the configuration. +See the <> for more information. ===== Setting up your tests without JUnit [[getting-started-documentation-snippets-setup-manual]] -The configuration when JUnit is not being used is largely similar to when it is being -used. This section describes the key differences. The {samples}/testng[TestNG sample] also -illustrates the approach. +The configuration when JUnit is not being used is largely similar to when it is being used. +This section describes the key differences. +The {samples}/testng[TestNG sample] also illustrates the approach. -The first difference is that you should use `ManualRestDocumentation` in place of -`JUnitRestDocumentation`. Also, you do not need the `@Rule` annotation. -the following example shows hos to use `ManualRestDocumentation`: +The first difference is that you should use `ManualRestDocumentation` in place of `JUnitRestDocumentation`. +Also, you do not need the `@Rule` annotation. +The following example shows how to use `ManualRestDocumentation`: ==== [source,java,indent=0] @@ -471,9 +437,8 @@ 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. +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: ==== @@ -509,8 +474,8 @@ include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.ja [[getting-started-documentation-snippets-invoking-the-service]] ==== Invoking the RESTful Service -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: +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"] @@ -518,28 +483,22 @@ service and document the request and response. The following examples show how t ---- include::{examples-dir}/com/example/mockmvc/InvokeService.java[tags=invoke-service] ---- -<1> Invoke the root (`/`) of the service and indicate that an `application/json` response -is required. +<1> Invoke the root (`/`) of the service and indicate that an `application/json` response is required. <2> Assert that the service produced the expected response. -<3> Document the call to the service, writing the snippets into a directory named `index` -(which is located beneath the configured output directory). The snippets are written by -a `RestDocumentationResultHandler`. You can obtain an instance of this class from the -static `document` method on -`org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`. +<3> Document the call to the service, writing the snippets into a directory named `index` (which is located beneath the configured output directory). +The snippets are written by a `RestDocumentationResultHandler`. +You can obtain an instance of this class from the static `document` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`. [source,java,indent=0,role="secondary"] .WebTestClient ---- include::{examples-dir}/com/example/webtestclient/InvokeService.java[tags=invoke-service] ---- -<1> Invoke the root (`/`) of the service and indicate that an `application/json` response -is required. +<1> Invoke the root (`/`) of the service and indicate that an `application/json` response is required. <2> Assert that the service produced the expected response. -<3> Document the call to the service, writing the snippets into a directory named `index` -(which is located beneath the configured output directory). The snippets are written by -a `Consumer` of the `ExchangeResult`. You can obtain such a consumer from the static -`document` method on -`org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`. +<3> Document the call to the service, writing the snippets into a directory named `index` (which is located beneath the configured output directory). +The snippets are written by a `Consumer` of the `ExchangeResult`. +You can obtain such a consumer from the static `document` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`. [source,java,indent=0,role="secondary"] .REST Assured @@ -548,11 +507,9 @@ include::{examples-dir}/com/example/restassured/InvokeService.java[tags=invoke-s ---- <1> Apply the specification that was initialized in the `@Before` method. <2> Indicate that an `application/json` response is required. -<3> Document the call to the service, writing the snippets into a directory named `index` -(which is located beneath the configured output directory). 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. +<3> Document the call to the service, writing the snippets into a directory named `index` (which is located beneath the configured output directory). +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. ==== @@ -566,18 +523,17 @@ By default, six snippets are written: * `/index/request-body.adoc` * `/index/response-body.adoc` -See <> for more information about these and other snippets -that can be produced by Spring REST Docs. +See <> for more information about these and other snippets that can be produced by Spring REST Docs. [[getting-started-using-the-snippets]] === Using the Snippets -Before using the generated snippets, you must create an `.adoc` source file. You can name -the file whatever you like as long as it has a `.adoc` suffix. The resulting HTML file -has the same name but with an `.html` suffix. The default location of the source files and -the resulting HTML files depends on whether you use Maven or Gradle: +Before using the generated snippets, you must create an `.adoc` source file. +You can name the file whatever you like as long as it has a `.adoc` suffix. +The resulting HTML file has the same name but with a `.html` suffix. +The default location of the source files and the resulting HTML files depends on whether you use Maven or Gradle: [cols="2,5,8"] |=== @@ -593,13 +549,9 @@ the resulting HTML files depends on whether you use Maven or Gradle: |=== -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 -<> to reference the snippets -output directory. The following example shows how to do so: +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 <> to reference the snippets output directory. +The following example shows how to do so: ==== [source,adoc,indent=0] diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index f8e50a52..16f9c9dc 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -18,8 +18,7 @@ Andy Wilkinson; Jay Bryant [[abstract]] -Document RESTful services by combining hand-written documentation with auto-generated -snippets produced with Spring MVC Test. +Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test, WebTestClient, or REST Assured. include::introduction.adoc[] include::getting-started.adoc[] diff --git a/docs/src/docs/asciidoc/introduction.adoc b/docs/src/docs/asciidoc/introduction.adoc index 29faddfe..a27e7295 100644 --- a/docs/src/docs/asciidoc/introduction.adoc +++ b/docs/src/docs/asciidoc/introduction.adoc @@ -1,26 +1,20 @@ [[introduction]] == Introduction -The aim of Spring REST Docs is to help you produce accurate and readable documentation for -your RESTful services. +The aim of Spring REST Docs is to help you produce accurate and readable documentation for your RESTful services. -Writing high-quality documentation is difficult. One way to ease that difficulty is to use -tools that are well-suited to the job. To this end, Spring REST Docs uses -https://asciidoctor.org[Asciidoctor] by default. Asciidoctor processes plain text and -produces HTML, styled and laid out to suit your needs. If you prefer, you can also -configure Spring REST Docs to use Markdown. +Writing high-quality documentation is difficult. +One way to ease that difficulty is to use tools that are well-suited to the job. +To this end, Spring REST Docs uses https://asciidoctor.org[Asciidoctor] by default. +Asciidoctor processes plain text and produces HTML, styled and laid out to suit your needs. +If you prefer, you can also configure Spring REST Docs to use Markdown. -Spring REST Docs uses snippets produced by tests written with Spring MVC's -{spring-framework-docs}/testing.html#spring-mvc-test-framework[test framework], Spring -WebFlux's {spring-framework-docs}/testing.html#webtestclient[`WebTestClient`] or -http://rest-assured.io[REST Assured 3]. This test-driven approach helps to guarantee -the accuracy of your service's documentation. If a snippet is incorrect, the test that -produces it fails. +Spring REST Docs uses snippets produced by tests written with Spring MVC's {spring-framework-docs}/testing.html#spring-mvc-test-framework[test framework], Spring WebFlux's {spring-framework-docs}/testing.html#webtestclient[`WebTestClient`] or http://rest-assured.io[REST Assured 3]. +This test-driven approach helps to guarantee the accuracy of your service's documentation. +If a snippet is incorrect, the test that produces it fails. -Documenting a RESTful service is largely about describing its resources. Two key parts -of each resource's description are the details of the HTTP requests that it consumes -and the HTTP responses that it produces. 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. +Documenting a RESTful service is largely about describing its resources. +Two key parts of each resource's description are the details of the HTTP requests that it consumes and the HTTP responses that it produces. +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. diff --git a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc index f8e18fbe..c1e29018 100644 --- a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc +++ b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc @@ -1,11 +1,10 @@ [[working-with-asciidoctor]] == Working with Asciidoctor -This section describes the aspects of working with Asciidoctor that are particularly -relevant to Spring REST Docs. +This section describes the aspects of working with Asciidoctor that are particularly relevant to Spring REST Docs. -NOTE: Asciidoc is the document format. Asciidoctor is the tool that produces content -(usually as HTML) from Asciidoc files (which end with `.adoc`). +NOTE: Asciidoc is the document format. +Asciidoctor is the tool that produces content (usually as HTML) from Asciidoc files (which end with `.adoc`). @@ -25,14 +24,11 @@ This section covers how to include Asciidoc snippets. [[working-with-asciidoctor-including-snippets-operation]] ==== Including Multiple Snippets for an Operation -You can use a macro named `operation` to import all or some of the snippets that have -been generated for a specific operation. It is made available by including -`spring-restdocs-asciidoctor` in your project's <>. +You can use a macro named `operation` to import all or some of the snippets that have been generated for a specific operation. +It is made available by including `spring-restdocs-asciidoctor` in your project's <>. -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: +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] @@ -41,11 +37,11 @@ operation::index[] ---- ==== -You can use the operation macro also supports a `snippets` attribute. The `snippets` -attribute to select the snippets that should be included. 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: +You can use the operation macro also supports a `snippets` attribute. +The `snippets` attribute to select the snippets that should be included. +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] @@ -80,8 +76,8 @@ The preceding example is the equivalent of the following: [[working-with-asciidoctor-including-snippets-operation-titles]] ===== Section Titles -For each snippet that is included by using the `operation` macro, a section with a title -is created. Default titles are provided for the following built-in snippets: +For each snippet that is included by using the `operation` macro, a section with a title is created. +Default titles are provided for the following built-in snippets: |=== | Snippet | Title @@ -114,13 +110,12 @@ is created. Default titles are provided for the following built-in snippets: | Response fields |=== -For snippets not listed in the preceding table, a default title is generated by replacing -`-` characters with spaces and capitalizing the first letter. For example, the title for a -snippet named `custom-snippet` `will be` "`Custom snippet`". +For snippets not listed in the preceding table, a default title is generated by replacing `-` characters with spaces and capitalizing the first letter. +For example, the title for a snippet named `custom-snippet` `will be` "`Custom snippet`". -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: +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] @@ -134,11 +129,9 @@ the `curl-request` snippet to be "Example request", you can use the following at [[working-with-asciidoctor-including-snippets-individual]] ==== Including Individual Snippets -The https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include -macro] is used to include individual snippets in your documentation. You can use the -`snippets` attribute (which is automatically set by `spring-restdocs-asciidoctor` -configured in the <>) to -reference the snippets output directory. The following example shows how to do so: +The https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include macro] is used to include individual snippets in your documentation. +You can use the `snippets` attribute (which is automatically set by `spring-restdocs-asciidoctor` configured in the <>) to reference the snippets output directory. +The following example shows how to do so: ==== [source,indent=0] @@ -152,19 +145,16 @@ reference the snippets output directory. The following example shows how to do s [[working-with-asciidoctor-customizing-tables]] === Customizing Tables -Many of the snippets contain a table in its default configuration. The appearance of the -table can be customized, either by providing some additional configuration when the -snippet is included or by using a custom snippet template. +Many of the snippets contain a table in its default configuration. +The appearance of the table can be customized, either by providing some additional configuration when the snippet is included or by using a custom snippet template. [[working-with-asciidoctor-customizing-tables-formatting-columns]] ==== Formatting Columns -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: +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] @@ -172,8 +162,7 @@ the following example shows, you can specify the widths of a table's columns by [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. +<1> The table's width is split across its two columns, with the second column being three times as wide as the first. ==== @@ -198,14 +187,13 @@ The following example shows how to do so: [[working-with-asciidoctor-customizing-tables-formatting-problems]] ==== Avoiding Table Formatting Problems -Asciidoctor uses the `|` character to delimit cells in a table. This can cause problems -if you want a `|` to appear in a cell's contents. You can avoid the problem by -escaping the `|` with a backslash -- in other words, by using `\|` rather than `|`. +Asciidoctor uses the `|` character to delimit cells in a table. +This can cause problems if you want a `|` to appear in a cell's contents. +You can avoid the problem by escaping the `|` with a backslash -- in other words, by using `\|` rather than `|`. -All of the default Asciidoctor snippet templates perform this escaping automatically by -using a Mustache lamba named `tableCellContent`. 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: +All of the default Asciidoctor snippet templates perform this escaping automatically by using a Mustache lamba named `tableCellContent`. +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: ==== ---- @@ -217,5 +205,4 @@ in a cell that contains the value of a `description` attribute: ==== Further Reading -See the https://asciidoctor.org/docs/user-manual/#tables[Tables section of the -Asciidoctor user manual] for more information about customizing tables. +See the https://asciidoctor.org/docs/user-manual/#tables[Tables section of the Asciidoctor user manual] for more information about customizing tables. diff --git a/docs/src/docs/asciidoc/working-with-markdown.adoc b/docs/src/docs/asciidoc/working-with-markdown.adoc index f32fb3d1..b6e00835 100644 --- a/docs/src/docs/asciidoc/working-with-markdown.adoc +++ b/docs/src/docs/asciidoc/working-with-markdown.adoc @@ -1,28 +1,24 @@ [[working-with-markdown]] == Working with Markdown -This section describes the aspects of working with Markdown that are particularly -relevant to Spring REST Docs. +This section describes the aspects of working with Markdown that are particularly relevant to Spring REST Docs. [[working-with-markdown-limitations]] === Limitations -Markdown was originally designed for people writing for the web and, as such, is not as -well-suited to writing documentation as Asciidoctor. Typically, these limitations are -overcome by using another tool that builds on top of Markdown. +Markdown was originally designed for people writing for the web and, as such, is not as well-suited to writing documentation as Asciidoctor. +Typically, these limitations are overcome by using another tool that builds on top of Markdown. -Markdown has no official support for tables. Spring REST Docs' default Markdown snippet -templates use https://michelf.ca/projects/php-markdown/extra/#table[Markdown Extra's table -format]. +Markdown has no official support for tables. +Spring REST Docs' default Markdown snippet templates use https://michelf.ca/projects/php-markdown/extra/#table[Markdown Extra's table format]. [[working-with-markdown-including-snippets]] === Including Snippets -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]. +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].