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

Merge pull request #575 from Jay Bryant

Browse Source 
* gh-575:
  Improve style and consistency of the documentation
This commit is contained in:
Andy Wilkinson
2019-02-11 15:06:06 +00:00
parent bc02ee0c1c 6a2d30a32e
commit 1675795960
9 changed files with 721 additions and 570 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/src/docs/asciidoc/configuration.adoc
View File

@@ -1,17 +1,18 @@
[[configuration]]
== Configuration
This section covers how to configure Spring REST Docs.
[[configuration-uris]]
=== Documented URIs
This section covers configuring documented URIs.
[[configuration-uris-mockmvc]]
==== MockMvc URI customization
==== MockMvc URI Customization
When using MockMvc, the default configuration for URIs documented by Spring REST Docs is:
When using MockMvc, the default configuration for URIs documented by Spring REST Docs is
as follows:
|===
|Setting |Default
@@ -26,16 +27,19 @@ When using MockMvc, the default configuration for URIs documented by Spring REST
|`8080`
|===
This configuration is applied by `MockMvcRestDocumentationConfigurer`. You can use its API
to change one or more of the defaults to suit your needs:
This configuration is applied by `MockMvcRestDocumentationConfigurer`. You can use its
API to change one or more of the defaults to suit your needs. The following example shows
how to do so:
====
[source,java,indent=0]
----
include::{examples-dir}/com/example/mockmvc/CustomUriConfiguration.java[tags=custom-uri-configuration]
----
====
NOTE: If the port is set to the default for the configured scheme (port 80 for HTTP or
port 443 for HTTPS), it will be omitted from any URIs in the generated snippets.
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`.
@@ -43,37 +47,43 @@ TIP: To configure a request's context path, use the `contextPath` method on
[[configuration-uris-rest-assured]]
==== REST Assured URI customization
==== 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 <<customizing-requests-and-responses-preprocessors-modify-uris, REST-Assured
specific preprocessor>> is provided for this purpose.
documented. A
<<customizing-requests-and-responses-preprocessors-modify-uris, REST-Assured-specific
preprocessor>> is provided for this purpose.
[[configuration-uris-webtestclient]]
==== WebTestClient URI customization
==== WebTestClient URI Customization
When using WebTestClient, the default base for URIs documented by Spring REST
Docs is `http://localhost:8080`. This base can be customized using the
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`]:
`baseUrl(String)` method on `WebTestClient.Builder`]. The following example shows how to
do so:
====
[source,java,indent=0]
----
include::{examples-dir}/com/example/webtestclient/CustomUriConfiguration.java[tags=custom-uri-configuration]
----
<1> Configure the base of documented URIs to be `https://api.example.com`.
====
[[configuration-snippet-encoding]]
=== Snippet encoding
=== Snippet Encoding
The default snippet encoding is `UTF-8`. You can change the default snippet encoding
using the `RestDocumentationConfigurer` API. For example, to 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"]
.MockMvc
----
@@ -91,20 +101,23 @@ include::{examples-dir}/com/example/webtestclient/CustomEncoding.java[tags=custo
----
include::{examples-dir}/com/example/restassured/CustomEncoding.java[tags=custom-encoding]
----
====
TIP: When Spring REST Docs converts a request or response's content to a String, the
`charset` specified in the `Content-Type` header will be used if it is available. In its
absence, the JVM's default `Charset` will be used. The JVM's default `Charset` can be
configured using 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` byusing the `file.encoding` system property.
[[configuration-snippet-template-format]]
=== 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 using the `RestDocumentationConfigurer` API:
box. You can change the default format by using the `RestDocumentationConfigurer` API.
The following examples show how to do so:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
@@ -122,25 +135,27 @@ include::{examples-dir}/com/example/webtestclient/CustomFormat.java[tags=custom-
----
include::{examples-dir}/com/example/restassured/CustomFormat.java[tags=custom-format]
----
====
[[configuration-default-snippets]]
=== Default snippets
=== Default Snippets
Six snippets are produced by default:
- `curl-request`
- `http-request`
- `http-response`
- `httpie-request`
- `request-body`
- `response-body`
* `curl-request`
* `http-request`
* `http-response`
* `httpie-request`
* `request-body`
* `response-body`
You can change the default snippet configuration during setup using the
`RestDocumentationConfigurer` API. For example, to only produce the `curl-request`
You can change the default snippet configuration during setup by using the
`RestDocumentationConfigurer` API. The following examples produce only the `curl-request`
snippet by default:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
@@ -158,35 +173,37 @@ include::{examples-dir}/com/example/webtestclient/CustomDefaultSnippets.java[tag
----
include::{examples-dir}/com/example/restassured/CustomDefaultSnippets.java[tags=custom-default-snippets]
----
====
[[configuration-default-preprocessors]]
=== Default operation preprocessors
=== Default Operation Preprocessors
You can configure default request and response preprocessors during setup using the
`RestDocumentationConfigurer` API. For example, to 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"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/CustomDefaultOperationPreprocessors.java[tags=custom-default-operation-preprocessors]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/CustomDefaultOperationPreprocessors.java[tags=custom-default-operation-preprocessors]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/CustomDefaultOperationPreprocessors.java[tags=custom-default-operation-preprocessors]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
====

13
docs/src/docs/asciidoc/contributing.adoc
View File

@@ -1,16 +1,17 @@
[[contributing]]
== Contributing
Spring REST Docs is intended to make it easy for you to produce high-quality documentation
for your RESTful services. However, we can't 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 http://stackoverflow.com[StackOverflow]
using the `spring-restdocs` tag. Similarly, we encourage you to help your fellow
You can ask questions about Spring REST Docs on http://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.
@@ -28,9 +29,9 @@ ideally, includes a test that reproduces it.
[[contributing-enhancements]]
=== Enhancements
If you'd like an enhancement to be made to Spring REST Docs, pull requests are most
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 is already being worked on. You may also want to
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.

93
docs/src/docs/asciidoc/customizing-requests-and-responses.adoc
View File

@@ -3,68 +3,74 @@
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's documented.
preprocessors that can be used to modify a request or response before it is documented.
Preprocessing is configured by calling `document` with an `OperationRequestPreprocessor`,
and/or an `OperationResponsePreprocessor`. Instances can be obtained using the
static `preprocessRequest` and `preprocessResponse` methods on `Preprocessors`. For
example:
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"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/PerTestPreprocessing.java[tags=preprocessing]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/PerTestPreprocessing.java[tags=preprocessing]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/PerTestPreprocessing.java[tags=preprocessing]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
====
Alternatively, you may want to apply the same preprocessors to every test. You can do
so by configuring the preprocessors using the `RestDocumentationConfigurer` API in your
`@Before` method. For example to remove the `Foo` header from all requests and pretty print
all responses:
Alternatively, you may want to apply the same preprocessors to every test. You can do so
by using the `RestDocumentationConfigurer` API in your `@Before` method to configure the
preprocessors. For example to remove the `Foo` header from all requests and pretty print
all responses, you could do one of the following (depending on your testing environment):
====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/EveryTestPreprocessing.java[tags=setup]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/EveryTestPreprocessing.java[tags=setup]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags=setup]
----
<1> Apply a request preprocessor that will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
====
Then, in each test, any configuration specific to that test can be performed. For example:
Then, in each test, you can perform any configuration specific to that test. The
following examples show how to do so:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
@@ -82,9 +88,10 @@ include::{examples-dir}/com/example/webtestclient/EveryTestPreprocessing.java[ta
----
include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags=use]
----
====
Various built in preprocessors, including those illustrated above, are available via the
static methods on `Preprocessors`. See <<Preprocessors, below>> for further details.
Various built-in preprocessors, including those illustrated above, are available through
the static methods on `Preprocessors`. See <<Preprocessors, below>> for further details.
@@ -94,7 +101,7 @@ static methods on `Preprocessors`. See <<Preprocessors, below>> for further deta
[[customizing-requests-and-responses-preprocessors-pretty-print]]
==== Pretty printing
==== Pretty Printing
`prettyPrint` on `Preprocessors` formats the content of the request or response
to make it easier to read.
@@ -102,18 +109,18 @@ to make it easier to read.
[[customizing-requests-and-responses-preprocessors-mask-links]]
==== Masking links
==== Masking Links
If you're documenting a Hypermedia-based API, you may want to encourage clients to
navigate the API using links rather than through the use of hard coded URIs. One way to do
this is to limit the use of URIs in the documentation. `maskLinks` on
`Preprocessors` replaces the `href` of any links in the response with `...`. A
different replacement can also be specified 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
==== 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.
@@ -124,18 +131,18 @@ response where the name matches any of the given regular expression patterns.
[[customizing-requests-and-responses-preprocessors-replace-patterns]]
==== Replacing patterns
==== Replacing Patterns
`replacePattern` on `Preprocessors` provides a general purpose mechanism for
replacing content in a request or response. Any occurrences of a regular expression are
replaced.
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
==== Modifying Request Parameters
`modifyParameters` on `Preprocessors` can be used to add, set, and remove request
You can use `modifyParameters` on `Preprocessors` to add, set, and remove request
parameters.
@@ -143,23 +150,23 @@ parameters.
[[customizing-requests-and-responses-preprocessors-modify-uris]]
==== Modifying URIs
TIP: If you are using MockMvc or a WebTestClient that is not bound to a server,
URIs should be customized by <<configuration-uris, changing the configuration>>.
TIP: If you use MockMvc or a WebTestClient that is not bound to a server,
you should customize URIs by <<configuration-uris, changing the configuration>>.
`modifyUris` on `Preprocessors` can be used to modify any URIs in a request
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
allows you to customize the URIs that appear in the documentation while testing a
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
==== 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 you only want to modify the content (body) of a request or response, consider
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`.

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

File diff suppressed because it is too large Load Diff

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

@@ -6,11 +6,10 @@ This section describes how to get started with Spring REST Docs.
[[getting-started-sample-applications]]
=== Sample applications
=== Sample Applications
If you want to jump straight in, a number of sample applications are available:
[cols="3,2,10"]
.MockMvc
|===
@@ -19,12 +18,12 @@ 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 using http://projects.spring.io/spring-data-rest/[Spring Data REST].
implemented by using http://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 using http://projects.spring.io/spring-hateoas/[Spring HATEOAS].
implemented by using http://projects.spring.io/spring-hateoas/[Spring HATEOAS].
|===
@@ -82,13 +81,10 @@ If you want to jump straight in, a number of sample applications are available:
Spring REST Docs has the following minimum requirements:
- Java 8
- Spring Framework 5 (5.0.2 or later)
* Java 8
* Spring Framework 5 (5.0.2 or later)
Additionally, the `spring-restdocs-restassured` module has the following minimum
requirements:
- REST Assured 3.0
Additionally, the `spring-restdocs-restassured` module requires REST Assured 3.0.
[[getting-started-build-configuration]]
=== Build configuration
@@ -96,9 +92,10 @@ requirements:
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 below.
and `pom.xml`, respectively, that you may wish to use as a reference. The key parts of
the configuration are described in the following listings:
====
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
.Maven
----
@@ -189,18 +186,21 @@ the configuration are described below.
<7> Configure the snippets directory as an input.
<8> 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
==== 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
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
The following listings show how to do so in both Maven and Gradle:
====
[source,xml,indent=0,role="primary"]
.Maven
----
@@ -254,14 +254,15 @@ from where it will be included in the jar file.
----
<1> Ensure that the documentation has been generated before the jar is built.
<2> Copy the generated documentation into the jar's `static/docs` directory.
====
[[getting-started-documentation-snippets]]
=== Generating 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
Spring WebFlux's {spring-framework-docs}/testing.html#webtestclient[`WebTestClient`], or
http://www.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.
@@ -269,25 +270,26 @@ response.
[[getting-started-documentation-snippets-setup]]
==== Setting up your tests
==== Setting up Your Tests
Exactly how you setup your tests depends on the test framework that you're using.
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
===== 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's annotated as a JUnit `@Rule`.
`public` `JUnitRestDocumentation` field that is annotated as a JUnit `@Rule`.
The following example shows how to do so:
====
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
----
====
By default, the `JUnitRestDocumentation` rule is automatically configured with an output
directory based on your project's build tool:
@@ -304,24 +306,29 @@ directory based on your project's build tool:
|===
The default can be overridden by providing an output directory when creating 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:
====
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
----
====
Next, provide an `@Before` method to configure MockMvc, WebTestClient or REST Assured:
Next, you must provide an `@Before` method to configure MockMvc, WebTestClient or REST
Assured. The following examples show how to do so:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/ExampleApplicationTests.java[tags=setup]
----
<1> The `MockMvc` instance is configured using a `MockMvcRestDocumentationConfigurer`. An
instance of this class can be obtained from the static `documentationConfiguration()`
<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`.
[source,java,indent=0,role="secondary"]
@@ -330,8 +337,8 @@ method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
include::{examples-dir}/com/example/webtestclient/ExampleApplicationTests.java[tags=setup]
----
<1> The `WebTestClient` instance is configured by adding a
`WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`. An instance of
this class can be obtained from the static `documentationConfiguration()` method on
`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"]
@@ -340,34 +347,40 @@ this class can be obtained from the static `documentationConfiguration()` method
include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tags=setup]
----
<1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a
`Filter`. An instance of this class can be obtained from the static
`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. Refer to the <<configuration, configuration section>> for more information.
configuration. See the <<configuration, configuration section>> for more information.
[[getting-started-documentation-snippets-setup-junit-5]]
===== Setting up your JUnit 5 tests
===== 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:
the `RestDocumentationExtension` to your test class.
The following example shows how to do so:
====
[source,java,indent=0]
----
@ExtendWith(RestDocumentationExtension.class)
public class JUnit5ExampleTests {
----
====
For testing a typical Spring application the `SpringExtension` should also be applied:
When testing a typical Spring application, you should also apply the `SpringExtension`:
====
[source,java,indent=0]
----
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class JUnit5ExampleTests {
----
====
The `RestDocumentationExtension` is automatically configured with an output directory
based on your project's build tool:
@@ -386,15 +399,17 @@ based on your project's build tool:
Next, provide a `@BeforeEach` method to configure MockMvc, WebTestClient, or REST Assured:
Next, you must provide a `@BeforeEach` method to configure MockMvc, WebTestClient, or
REST Assured. The following listings show how to do so:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/ExampleApplicationJUnit5Tests.java[tags=setup]
----
<1> The `MockMvc` instance is configured using a `MockMvcRestDocumentationConfigurer`. An
instance of this class can be obtained from the static `documentationConfiguration()`
<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`.
[source,java,indent=0,role="secondary"]
@@ -403,8 +418,8 @@ method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
include::{examples-dir}/com/example/webtestclient/ExampleApplicationJUnit5Tests.java[tags=setup]
----
<1> The `WebTestClient` instance is configured by adding a
`WebTestClientRestDocumentationConfigurer` as an `ExchangeFilterFunction`. An instance of
this class can be obtained from the static `documentationConfiguration()` method on
`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"]
@@ -413,12 +428,13 @@ this class can be obtained from the static `documentationConfiguration()` method
include::{examples-dir}/com/example/restassured/ExampleApplicationJUnit5Tests.java[tags=setup]
----
<1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a
`Filter`. An instance of this class can be obtained from the static
`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. Refer to the <<configuration, configuration section>> for more information.
configuration. See the <<configuration, configuration section>> for more information.
@@ -429,18 +445,23 @@ The configuration when JUnit is not being used is largely similar to when it is
used. This section describes the key differences. The {samples}/testng[TestNG sample] also
illustrates the approach.
The first difference is that `ManualRestDocumentation` should be used in place of
`JUnitRestDocumentation` and there's no need for the `@Rule` annotation:
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`:
====
[source,java,indent=0]
----
private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
----
====
Secondly, `ManualRestDocumentation.beforeTest(Class, String)`
must be called before each test. This can be done as part of the method that is
configuring 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:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
@@ -458,21 +479,25 @@ include::{examples-dir}/com/example/webtestclient/ExampleApplicationTestNgTests.
----
include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.java[tags=setup]
----
====
Lastly, `ManualRestDocumentation.afterTest` must be called after each test. For example,
with TestNG:
Finally, you must call `ManualRestDocumentation.afterTest` after each test.
The following example shows how to do so with TestNG:
====
[source,java,indent=0]
----
include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.java[tags=teardown]
----
====
[[getting-started-documentation-snippets-invoking-the-service]]
==== Invoking the RESTful service
==== Invoking the RESTful Service
Now that the testing framework has been configured, it can be used to invoke the RESTful
service and document the request and response. For example:
Now that you have configured the testing framework, you can use it to invoke the RESTful
service and document the request and response. The following examples show how to do so:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
@@ -482,8 +507,8 @@ include::{examples-dir}/com/example/mockmvc/InvokeService.java[tags=invoke-servi
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`
that will be located beneath the configured output directory. The snippets are written by
a `RestDocumentationResultHandler`. An instance of this class can be obtained from the
(which is located beneath the configured output directory). The snippets are written by
a `RestDocumentationResultHandler`. You can obtain an instance of this clas from the
static `document` method on
`org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
@@ -496,24 +521,26 @@ include::{examples-dir}/com/example/webtestclient/InvokeService.java[tags=invoke
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`
that will be located beneath the configured output directory. The snippets are written by
a `Consumer` of the `ExchangeResult`. Such a consumer can be obtained from the static
`document` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`.
(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
----
include::{examples-dir}/com/example/restassured/InvokeService.java[tags=invoke-service]
----
<1> Apply the specification that was initialised in the `@Before` method.
<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`
that will be located beneath the configured output directory. The snippets are written by
a `RestDocumentationFilter`. An instance of this class can be obtained from the
static `document` method on `RestAssuredRestDocumentation` in the
(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.
====
By default, six snippets are written:
@@ -524,18 +551,18 @@ By default, six snippets are written:
* `<output-directory>/index/request-body.adoc`
* `<output-directory>/index/response-body.adoc`
Refer to <<documenting-your-api>> for more information about these and other snippets
See <<documenting-your-api>> for more information about these and other snippets
that can be produced by Spring REST Docs.
[[getting-started-using-the-snippets]]
=== Using the snippets
=== Using the Snippets
Before using the generated snippets, a `.adoc` source file must be created. You can name
the file whatever you like as long as it has a `.adoc` suffix. The result HTML file will
have the same name but with a `.html` suffix. The default location of the source files and
the resulting HTML files depends on whether you are using 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 an `.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"]
|===
@@ -551,14 +578,17 @@ the resulting HTML files depends on whether you are using Maven or Gradle:
|===
The generated snippets can then be included in the manually created Asciidoctor file from
above using the
You can then include the generated snippets in the manually created Asciidoc file
(described earlier in this section) by using the
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include macro].
The `snippets` attribute that is automatically set by `spring-restdocs-asciidoctor`
configured in the <<getting-started-build-configuration, build
configuration>> can be used to reference the snippets output directory. For example:
You can use the `snippets` attribute that is automatically set by
`spring-restdocs-asciidoctor` configured in the
<<getting-started-build-configuration,build configuration>> to reference the snippets
output directory. The following example shows how to do so:
====
[source,adoc,indent=0]
----
\include::{snippets}/index/curl-request.adoc[]
----
====

4
docs/src/docs/asciidoc/index.adoc
View File

@@ -1,5 +1,5 @@
= Spring REST Docs
Andy Wilkinson
Andy Wilkinson; Jay Bryant
:doctype: book
:icons: font
:source-highlighter: highlightjs
@@ -28,4 +28,4 @@ include::customizing-requests-and-responses.adoc[]
include::configuration.adoc[]
include::working-with-asciidoctor.adoc[]
include::working-with-markdown.adoc[]
include::contributing.adoc[]
include::contributing.adoc[]

24
docs/src/docs/asciidoc/introduction.adoc
View File

@@ -1,26 +1,26 @@
[[introduction]]
== Introduction
The aim of Spring REST Docs is to help you to produce documentation for your RESTful
services that is accurate and readable.
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
http://asciidoctor.org[Asciidoctor] by default. Asciidoctor processes plain text and
produces HTML, styled and layed out to suit your needs. If you prefer, Spring REST Docs
can also be configured to use Markdown.
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 makes use of snippets produced by tests written with Spring MVC's
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://www.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 will fail.
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 allows you to 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 to
document your service's API rather than its implementation. It also frees you to evolve
the implementation without having to rework the documentation.
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.

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

@@ -1,9 +1,12 @@
[[working-with-asciidoctor]]
== Working with Asciidoctor
This section describes any aspects of working with Asciidoctor that are particularly
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`).
[[working-with-asciidoctor-resources]]
@@ -15,43 +18,50 @@ relevant to Spring REST Docs.
[[working-with-asciidoctor-including-snippets]]
=== Including snippets
=== Including Snippets
This section covers how to include Asciidoc snippets.
[[working-with-asciidoctor-including-snippets-operation]]
==== Including multiple snippets for an operation
==== Including Multiple Snippets for an Operation
A macro named `operation` can be used to import all or some of the snippets that have
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 <<getting-started-build-configuration,
build configuration>>.
WARNING: If you are using Gradle and its daemon or support for continuous builds, do not
WARNING: If you use Gradle and its daemon or support for continuous builds, do not
use version 1.5.6 of the `org.asciidoctor.convert` plugin. It contains a
https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/222[regression] that
prevents extensions from working reliably.
The target of the macro is the name of the operation. In its simplest form, the macro
can be used to include all of the snippets for an operation, as shown in the following
The target of the macro is the name of the operation. In its simplest form, you can use
the macro to include all of the snippets for an operation, as shown in the following
example:
====
[source,indent=0]
----
operation::index[]
----
====
The operation macro also supports a `snippets` attribute. The `snippets` attribute can be
used 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]
----
operation::index[snippets='curl-request,http-request,http-response']
----
====
This is the equivalent of the following:
The preceding example is the equivalent of the following:
====
[source,adoc,indent=0]
----
[[example_curl_request]]
@@ -70,78 +80,82 @@ This is the equivalent of the following:
\include::{snippets}/index/http-response.adoc[]
----
====
[[working-with-asciidoctor-including-snippets-operation-titles]]
===== Section titles
===== Section Titles
For each snippet that's including using `operation`, a section with a title will be
created. Default titles are provided for the 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
| curl-request
| `curl-request`
| Curl Request
| http-request
| `http-request`
| HTTP request
| http-response
| `http-response`
| HTTP response
| httpie-request
| `httpie-request`
| HTTPie request
| links
| `links`
| Links
| request-body
| `request-body`
| Request body
| request-fields
| `request-fields`
| Request fields
| response-body
| `response-body`
| Response body
| response-fields
| `response-fields`
| Response fields
|===
For snippets not listed in the table above, a default title will be generated by replacing
`-` characters with spaces and capitalising 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`".
The default titles can be customized 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", 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]
----
:operation-curl-request-title: Example request
----
====
[[working-with-asciidoctor-including-snippets-individual]]
==== Including individual snippets
==== Including Individual Snippets
The http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
macro] is used to include individual snippets in your documentation. The `snippets`
attribute that is automatically set by `spring-restdocs-asciidoctor` configured in the
<<getting-started-build-configuration, build configuration>> can be used to reference the
snippets output directory. For example:
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 <<getting-started-build-configuration, build configuration>>) to
reference the snippets output directory. The following example shows how to do so:
====
[source,indent=0]
----
\include::{snippets}/index/curl-request.adoc[]
----
====
[[working-with-asciidoctor-customizing-tables]]
=== 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
@@ -150,55 +164,63 @@ snippet is included or by using a custom snippet template.
[[working-with-asciidoctor-customizing-tables-formatting-columns]]
==== Formatting columns
==== Formatting Columns
Asciidoctor has rich support for
http://asciidoctor.org/docs/user-manual/#cols-format[formatting a table's columns]. For
example, the widths of a table's columns can be specified using the `cols` attribute:
http://asciidoctor.org/docs/user-manual/#cols-format[formatting a table's columns]. As the
following example shows, you can specify the widths of a table's columns by using the
`cols` attribute:
====
[source,indent=0]
----
[cols="1,3"] <1>
\include::{snippets}/index/links.adoc[]
----
<1> The table's width will be 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.
====
[[working-with-asciidoctor-customizing-tables-title]]
==== Configuring the title
==== Configuring the Title
The title of a table can be specified using a line prefixed by a `.`:
You can specify the title of a table by using a line prefixed by a `.`.
The following example shows how to do so:
====
[source,indent=0]
----
.Links <1>
\include::{snippets}/index/links.adoc[]
----
<1> The table's title will be `Links`.
====
[[working-with-asciidoctor-customizing-tables-formatting-problems]]
==== Avoiding table 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. The problem can be avoided by
escaping the `|` with a backslash, i.e. by using `\|` rather than `|`.
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
use a Mustache lamba named `tableCellContent`. If you write your own custom templates
you may want to use this lamba. For example, to escape `|` characters
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:
====
----
| {{#tableCellContent}}{{description}}{{/tableCellContent}}
----
====
==== Further reading
==== Further Reading
Refer to the http://asciidoctor.org/docs/user-manual/#tables[Tables section of
the Asciidoctor user manual] for more information about customizing tables.
See the http://asciidoctor.org/docs/user-manual/#tables[Tables section of the
Asciidoctor user manual] for more information about customizing tables.

12
docs/src/docs/asciidoc/working-with-markdown.adoc
View File

@@ -1,7 +1,7 @@
[[working-with-markdown]]
== Working with Markdown
This section describes any aspects of working with Markdown that are particularly
This section describes the aspects of working with Markdown that are particularly
relevant to Spring REST Docs.
@@ -9,9 +9,9 @@ relevant to Spring REST Docs.
[[working-with-markdown-limitations]]
=== Limitations
Markdown was originally designed for people writing for the web and, as such, isn't
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
@@ -20,9 +20,9 @@ format].
[[working-with-markdown-including-snippets]]
=== 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's particularly well-suited to
tool that supports this functionality. One example that is particularly well-suited to
documenting APIs is https://github.com/tripit/slate[Slate].