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

Polish the documentation

Browse Source
This commit is contained in:
Andy Wilkinson
2015-09-08 15:48:11 +01:00
parent 63e7466304
commit fe84aef912
4 changed files with 47 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -38,7 +38,7 @@ TIP: To configure a request's context path, use the `contextPath` method on
=== Snippet encoding
The default encoding used by Asciidoctor is `UTF-8`. Spring REST Docs adopts the same
default for the snippets that it generated. If you require an encoding other than `UTF-8`,
default for the snippets that it generates. If you require an encoding other than `UTF-8`,
use `RestDocumentationConfigurer` to configure it:
[source,java,indent=0]

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

@@ -7,7 +7,8 @@ preprocessors that can be used to modify a request or response before it's docum
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`:
static `preprocessRequest` and `preprocessResponse` methods on `Preprocessors`. For
example:
[source,java,indent=0]
----
@@ -42,20 +43,25 @@ include::{examples-dir}/com/example/PreprocessingEveryTest.java[tags=use]
use of `alwaysDo` above.
Various built in preprocessors, including those illustrated above, are available via the
static methods on `Preprocessors`. See below for further details.
static methods on `Preprocessors`. See <<Preprocessors, below>> for further details.
[[customizing-requests-and-responses-pretty-printing]]
=== Pretty printing
[[customizing-requests-and-responses-preprocessors]]
=== Preprocessors
[[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.
[[customizing-requests-and-responses-masking-links]]
=== Masking links
[[customizing-requests-and-responses-preprocessors-mask-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
@@ -65,16 +71,16 @@ different replacement can also be specified if you wish.
[[customizing-requests-and-responses-removing-headers]]
=== Removing headers
[[customizing-requests-and-responses-preprocessors-remove-headers]]
==== Removing headers
`removeHeaders` on `Preprocessors` removes any occurrences of the named headers
from the request or response.
[[customizing-requests-and-responses-replacing-patterns]]
=== Replacing 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 of a regular expression are

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

@@ -57,9 +57,9 @@ response.
[[documenting-your-api-request-response-payloads]]
=== Request and response payloads
In addition to the Hypermedia-specific support <<documenting-your-api-hypermedia,described
In addition to the hypermedia-specific support <<documenting-your-api-hypermedia,described
above>>, support for general documentation of request and response payloads is also
provided:
provided. For example:
[source,java,indent=0]
----
@@ -204,26 +204,27 @@ method will be included in the documentation.
=== Request parameters
A request's parameters can be documented using `requestParameters`. Request parameters
can be included in a `GET` requests query string:
can be included in a `GET` request's query string. For example:
[source,java,indent=0]
----
include::{examples-dir}/com/example/RequestParameters.java[tags=request-parameters-query-string]
----
<1> Perform a `GET` request with two parameters in the query string.
<1> Perform a `GET` request with two parameters, `page` and `per_page` in the query
string.
<2> Produce a snippet describing the request's parameters. Uses the static
`requestParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
<3> Document a parameter named `page`. Uses the static `parameterWithName` method on
<3> Document the `page` parameter. Uses the static `parameterWithName` method on
`org.springframework.restdocs.request.RequestDocumentation`.
<4> Document a parameter named `per_page`.
<4> Document the `per_page` parameter.
They can also be included as form data in the body of a POST request:
Request parameters can also be included as form data in the body of a POST request:
[source,java,indent=0]
----
include::{examples-dir}/com/example/RequestParameters.java[tags=request-parameters-form-data]
----
<1> Perform a `POST` request with a single parameter.
<1> Perform a `POST` request with a single parameter, `username`.
In both cases, the result is a snippet named `request-parameters.adoc` that contains a
table describing the parameters that are supported by the resource.
@@ -237,18 +238,18 @@ request parameter is not found in the request.
[[documenting-your-api-path-parameters]]
=== Path parameters
A request's path parameters can be documented using `pathParameters`
A request's path parameters can be documented using `pathParameters`. For example:
[source,java,indent=0]
----
include::{examples-dir}/com/example/PathParameters.java[tags=path-parameters]
----
<1> Build the request. Uses the static `get` method on `RestDocumentationRequestBuilders`.
<1> Perform a `GET` request with two path parameters, `latitude` and `longitude`.
<2> Produce a snippet describing the request's path parameters. Uses the static
`pathParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
<3> Document a parameter named `longitude`. Uses the static `parameterWithName` method on
<3> Document the parameter named `latitude`. Uses the static `parameterWithName` method on
`org.springframework.restdocs.request.RequestDocumentation`.
<4> Document a parameter named `latitude`.
<4> Document the parameter named `longitude`.
The result is a snippet named `path-parameters.adoc` that contains a table describing
the path parameters that are supported by the resource.
@@ -268,7 +269,7 @@ built using one of the methods on `RestDocumentationRequestBuilders` rather than
Spring REST Docs provides a number of classes that can help you to document constraints.
An instance of `ConstraintDescriptions` can be used to access descriptions of a class's
constraints:
constraints. For example:
[source,java,indent=0]
----
@@ -400,8 +401,8 @@ are supported:
For example, `document("{method-name}")` in a test method named `creatingANote` will write
snippets into a directory named `creating-a-note`.
The `{step}` parameter is particularly useful in combination with Spring MVC Test's
`alwaysDo` functionality. It allows documentation to be configured once in a setup method:
A parameterized output directory is particularly useful in combination with Spring MVC
Test's `alwaysDo` functionality. It allows documentation to be configured once in a setup method:
[source,java,indent=0]
----

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

@@ -13,8 +13,7 @@ If you want to jump straight in, there are two sample applications available.
http://projects.spring.io/spring-hateoas/[Spring HATEOAS] and
{samples}/rest-notes-spring-data-rest[the other] uses
http://projects.spring.io/spring-data-rest/[Spring Data REST]. Both samples use
Spring REST Docs to produce a detailed API guide and a getting started walkthrough. You
can use either Gradle or Maven to build them.
Spring REST Docs to produce a detailed API guide and a getting started walkthrough.
In each sample the source for the documentation can be found in `src/main/asciidoc`.
`api-guide.adoc` produces an API guide for the service. `getting-started-guide.adoc`
@@ -36,7 +35,7 @@ The first step in using Spring REST Docs is to configure your project's build.
[[getting-started-build-configuration-gradle]]
==== Gradle build configuration
The {samples/rest-notes-spring-hateoas}[Spring HATEOAS sample] contains a `build.gradle`
The {samples}rest-notes-spring-hateoas[Spring HATEOAS sample] contains a `build.gradle`
file that you may wish to use as a reference. The key parts of the configuration are
described below.
@@ -65,7 +64,7 @@ described below.
}
----
<1> Apply the Asciidoctor plugin.
<2> Add a dependency on spring-restdocs in the `testCompile` configuration.
<2> Add a dependency on `spring-restdocs-mockmvc` in the `testCompile` configuration.
<3> Configure a property to define the output location for generated snippets.
<4> Configure the `test` task to add the snippets directory as an output.
<5> Configure the `asciidoctor` task
@@ -100,7 +99,7 @@ directory:
[[getting-started-build-configuration-maven]]
==== Maven build configuration
The {samples/rest-notes-spring-data-rest}[Spring Data REST sample] contains a `pom.xml`
The {samples}rest-notes-spring-data-rest[Spring Data REST sample] contains a `pom.xml`
file that you may wish to use as a reference. The key parts of the configuration are
described below.
@@ -135,7 +134,7 @@ described below.
<executions>
<execution>
<id>generate-docs</id>
<phase>package</phase> <5>
<phase>package</phase> <6>
<goals>
<goal>process-asciidoc</goal>
</goals>
@@ -143,7 +142,7 @@ described below.
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<snippets>${snippetsDirectory}</snippets>
<snippets>${snippetsDirectory}</snippets> <5>
</attributes>
</configuration>
</execution>
@@ -157,9 +156,10 @@ described below.
<2> Configure a property to define the output location for generated snippets.
<3> Add the SureFire plugin and configure it to include files whose names end with
`Documentation.java`.
<4> Add the Asciidoctor plugin and configure it to define an attribute named `snippets`
that can be used when including the generated snippets in your documentation.
<5> [[getting-started-build-configuration-maven-plugin-phase]] If you want to
<4> Add the Asciidoctor plugin
<5> Define an attribute named `snippets` that can be used when including the generated
snippets in your documentation.
<6> [[getting-started-build-configuration-maven-plugin-phase]] If you want to
<<getting-started-build-configuration-maven-packaging, package the documentation>> in your
project's jar you should use the `prepare-package` phase.
@@ -226,8 +226,8 @@ documentation snippets for the result's request and response.
==== Setting up Spring MVC test
The first step in generating documentation snippets is to declare a `public`
`RestDocumentation` that's annotated as a JUnit `@Rule` and to provide an `@Before` method
that creates a `MockMvc` instance:
`RestDocumentation` field that's annotated as a JUnit `@Rule` and to provide an `@Before`
method that creates a `MockMvc` instance:
[source,java,indent=0]
----
@@ -250,7 +250,7 @@ sensible defaults and also provides an API for customizing the configuration. Re
==== Invoking the RESTful service
Now that a `MockMvc` instance has been created, it can be used to invoke the RESTful
service and document the request and response.
service and document the request and response. For example:
[source,java,indent=0]
----
@@ -282,7 +282,7 @@ that can be produced by Spring REST Docs.
The generated snippets can be included in your documentation using the
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include macro].
The `snippets` attribute specified in the <<getting-started-build-configuration, build
configuration>> can be used to reference the snippets output directory, for example:
configuration>> can be used to reference the snippets output directory. For example:
[source,adoc,indent=0]
----