diff --git a/docs/src/docs/asciidoc/configuration.adoc b/docs/src/docs/asciidoc/configuration.adoc index acd0fd2f..0dd0779b 100644 --- a/docs/src/docs/asciidoc/configuration.adoc +++ b/docs/src/docs/asciidoc/configuration.adoc @@ -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] diff --git a/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc b/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc index 64830cd9..f88a5879 100644 --- a/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc +++ b/docs/src/docs/asciidoc/customizing-requests-and-responses.adoc @@ -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 <> 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 diff --git a/docs/src/docs/asciidoc/documenting-your-api.adoc b/docs/src/docs/asciidoc/documenting-your-api.adoc index c4352df4..e5451383 100644 --- a/docs/src/docs/asciidoc/documenting-your-api.adoc +++ b/docs/src/docs/asciidoc/documenting-your-api.adoc @@ -57,9 +57,9 @@ response. [[documenting-your-api-request-response-payloads]] === Request and response payloads -In addition to the Hypermedia-specific support <>, support for general documentation of request and response payloads is also -provided: +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] ---- diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index c013ce47..8273b296 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -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. generate-docs - package <5> + package <6> process-asciidoc @@ -143,7 +142,7 @@ described below. html book - ${snippetsDirectory} + ${snippetsDirectory} <5> @@ -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 <> 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 <> 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] ----