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

Format documentation using one sentence per line

Browse Source 
Closes gh-772
This commit is contained in:
Andy Wilkinson
2022-01-10 15:50:10 +00:00
parent d4d83f293a
commit 87e7a7bb3b
11 changed files with 545 additions and 777 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
CONTRIBUTING.md
View File

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

20
README.md
View File

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

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

@@ -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
<<customizing-requests-and-responses-preprocessors-modify-uris, REST-Assured-specific
preprocessor>> 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 <<customizing-requests-and-responses-preprocessors-modify-uris, REST-Assured-specific preprocessor>> 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"]

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

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

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

@@ -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 <<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.
@@ -103,70 +100,58 @@ the static methods on `Preprocessors`. See <<Preprocessors, below>> 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 <<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>>.
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`.

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

File diff suppressed because it is too large Load Diff

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

@@ -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:
</plugins>
</build>
----
<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
<<getting-started-build-configuration-packaging-the-documentation, included in the package>>.
<4> Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin. This
will automatically configure the `snippets` attribute for use in your `.adoc` files to
point to `target/generated-snippets`. It will also allow you to use the `operation` block
macro.
<3> Using `prepare-package` allows the documentation to be <<getting-started-build-configuration-packaging-the-documentation, included in the package>>.
<4> Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin.
This will automatically configure the `snippets` attribute for use in your `.adoc` files to point to `target/generated-snippets`.
It will also allow you to use the `operation` block macro.
[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:
</plugin>
----
<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 <<configuration, configuration section>> for more information.
The configurer applies sensible defaults and also provides an API for customizing the configuration.
See the <<configuration, configuration section>> 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 <<configuration, configuration section>> for more information.
The configurer applies sensible defaults and also provides an API for customizing the configuration.
See the <<configuration, configuration section>> for more information.
===== Setting up your tests without JUnit
[[getting-started-documentation-snippets-setup-manual]]
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:
* `<output-directory>/index/request-body.adoc`
* `<output-directory>/index/response-body.adoc`
See <<documenting-your-api>> for more information about these and other snippets
that can be produced by Spring REST Docs.
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
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
<<getting-started-build-configuration,build configuration>> 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 <<getting-started-build-configuration,build configuration>> to reference the snippets output directory.
The following example shows how to do so:
====
[source,adoc,indent=0]

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

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

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

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

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

@@ -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 <<getting-started-build-configuration,
build configuration>>.
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>>.
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 <<getting-started-build-configuration, build configuration>>) 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 <<getting-started-build-configuration, build configuration>>) 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.

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

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