diff --git a/docs/src/docs/asciidoc/configuration.adoc b/docs/src/docs/asciidoc/configuration.adoc index 8824b28a..ed9b2103 100644 --- a/docs/src/docs/asciidoc/configuration.adoc +++ b/docs/src/docs/asciidoc/configuration.adoc @@ -6,7 +6,7 @@ [[configuration-uris]] === Documented URIs -The default configuration for URIs documented by Spring REST docs is: +The default configuration for URIs documented by Spring REST Docs is: |=== |Setting |Default @@ -37,7 +37,7 @@ include::{examples-dir}/com/example/CustomUriConfiguration.java[tags=custom-uri- [[configuration-snippet-encoding]] === Snippet encoding -The default encoding used by Asciidoc is `UTF-8`. Spring REST docs adopts the same +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`, use `RestDocumentationConfigurer` to configure it: diff --git a/docs/src/docs/asciidoc/contributing.adoc b/docs/src/docs/asciidoc/contributing.adoc index 04b7f450..660c3c09 100644 --- a/docs/src/docs/asciidoc/contributing.adoc +++ b/docs/src/docs/asciidoc/contributing.adoc @@ -1,7 +1,7 @@ [[contributing]] == Contributing -Spring REST Docs is intended to make is easy for you to produce high-quality documentation +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. diff --git a/docs/src/docs/asciidoc/customizing-responses.adoc b/docs/src/docs/asciidoc/customizing-responses.adoc index 08613f93..fe2eb415 100644 --- a/docs/src/docs/asciidoc/customizing-responses.adoc +++ b/docs/src/docs/asciidoc/customizing-responses.adoc @@ -16,7 +16,7 @@ include::{examples-dir}/com/example/ResponsePostProcessing.java[tags=general] ---- <1> Call `modifyResponseTo` to configure response modifications, passing in one or more `ResponsePostProcessor` implementations. -<2> Proceed with documenting the call +<2> Proceed with documenting the call. [[customizing-responses-pretty-printing]] diff --git a/docs/src/docs/asciidoc/documenting-your-api.adoc b/docs/src/docs/asciidoc/documenting-your-api.adoc index d2ac4057..a7652ed4 100644 --- a/docs/src/docs/asciidoc/documenting-your-api.adoc +++ b/docs/src/docs/asciidoc/documenting-your-api.adoc @@ -15,17 +15,17 @@ https://en.wikipedia.org/wiki/HATEOAS[Hypermedia-based] API: ---- include::{examples-dir}/com/example/Hypermedia.java[tag=links] ---- -<1> `withLinks` is used to describe the expected links -<2> Expects a link whose rel is `alpha`. Uses the static `linkWithRel` method on +<1> Use `withLinks` is to describe the expected links. +<2> Expect a link whose rel is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`. -<3> Expects a link whose rel is `bravo` +<3> Expect a link whose rel is `bravo`. The result is a snippet named `links.adoc` that contains a table describing the resource's links. When documenting links, the test will fail if an undocumented link is found in the response. Similarly, the test will also fail if a documented link is not found in the -response and the link has not be marked as optional. +response and the link has not been marked as optional. @@ -46,7 +46,7 @@ provide one of the built-in `LinkExtractor` implementations to `withLinks`. For ---- include::{examples-dir}/com/example/Hypermedia.java[tag=explicit-extractor] ---- -<1> Indicate that the links are in HAL format using the `halLinks` static method on +<1> Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.LinkExtractors`. If your API represents its links in a format other than Atom or HAL you can provide your @@ -64,11 +64,11 @@ provided: ---- include::{examples-dir}/com/example/Payload.java[tags=response] ---- -<1> `withResponseFields` is used to describe the expected fields in the response payload. +<1> Use `withResponseFields` to describe the expected fields in the response payload. To document a request `withRequestFields` can be used. -<2> Expects a field with the path `contact`. Uses the static `fieldWithPath` method on +<2> Expect a field with the path `contact`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`. -<3> Expects a field with the path `contact.email` +<3> Expect a field with the path `contact.email`. The result is a snippet that contains a table describing the fields. For requests this snippet is named `request-fields.adoc`. For responses this snippet is named @@ -76,7 +76,7 @@ snippet is named `request-fields.adoc`. For responses this snippet is named When documenting fields, the test will fail if an undocumented field is found in the payload. Similarly, the test will also fail if a documented field is not found in the -payload and the field has not be marked as optional. For payloads with a hierarchical +payload and the field has not been marked as optional. For payloads with a hierarchical structure, documenting a field is sufficient for all of its descendants to also be treated as having been documented. @@ -133,7 +133,7 @@ The following paths are all present: [[documenting-your-api-request-response-payloads-field-types]] ==== Field types -When a field is documented, Spring REST docs will attempt to determine its type by +When a field is documented, Spring REST Docs will attempt to determine its type by examining the payload. Seven different types are supported: [cols="1,3"] @@ -182,10 +182,10 @@ A request's query parameters can be documented using `withQueryParameters` ---- include::{examples-dir}/com/example/QueryParameters.java[tags=query-parameters] ---- -<1> `withQueryParameters` is used to describe the query parameters -<2> Documents a parameter named `page`. Uses the static `parameterWithName` method on +<1> Use `withQueryParameters` to describe the query parameters. +<2> Document a parameter named `page`. Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`. -<3> Documents a parameter named `per_page` +<3> Document a parameter named `per_page`. The result is a snippet named `query-parameters.adoc` that contains a table describing the query parameters that are supported by the resource. diff --git a/docs/src/docs/asciidoc/getting-started.adoc b/docs/src/docs/asciidoc/getting-started.adoc index 4b00b430..bbb0af76 100644 --- a/docs/src/docs/asciidoc/getting-started.adoc +++ b/docs/src/docs/asciidoc/getting-started.adoc @@ -1,7 +1,7 @@ [[getting-started]] == Getting started -This section describes how to get started with Spring REST docs. +This section describes how to get started with Spring REST Docs. @@ -66,9 +66,9 @@ use as a reference. The key parts of the configuration are described below. dependsOn test } ---- -<1> Apply the Asciidoctor plugin -<2> Add a dependency on spring-restdocs in the `testCompile` configuration: -<3> Configure a property to define the output location for generated snippets: +<1> Apply the Asciidoctor plugin. +<2> Add a dependency on spring-restdocs in the `testCompile` configuration. +<3> Configure a property to define the output location for generated snippets. <4> Configure the `test` task with the `org.springframework.restdocs.outputDir` system property. This property controls the location into which Spring REST Docs will write the snippets that it generates. @@ -159,12 +159,12 @@ use as a reference. The key parts of the configuration are described below. ---- -<1> Add a dependency on `spring-restdocs` in the `test` scope -<2> Configure a property to define the output location for generated snippets +<1> Add a dependency on `spring-restdocs` in the `test` scope. +<2> Configure a property to define the output location for generated snippets. <3> Configure the SureFire plugin with the `org.springframework.restdocs.outputDir` system -property. This property controls the location into which Spring REST docs will write the +property. This property controls the location into which Spring REST Docs will write the snippets that it generates. The plugin is also configured to include files whose names end -with `Documentation.java`: +with `Documentation.java`. <4> Configure the Asciidoctor plugin and define an attribute named `snippets`. You can then use this attribute when including the generated snippets in your documentation. <5> [[getting-started-build-configuration-maven-plugin-phase]] If you want to @@ -216,7 +216,7 @@ be included in the project's jar: ---- -<1> The existing declaration for the Asciidoctor 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 and the resource plugin must run after the Asciidoctor plugin. @@ -260,8 +260,8 @@ service and document the request and response. include::{examples-dir}/com/example/InvokeService.java[tags=invoke-service] ---- <1> Invoke the root (`/`) of the service an indicate that an `application/json` response -is required -<2> Assert that the service is produced the expected response +is required. +<2> Assert that the service is 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 diff --git a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc index c942ad23..dd0d68d2 100644 --- a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc +++ b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc @@ -48,7 +48,7 @@ example, the widths of a table's columns can be specified using the `cols` attri [source,adoc,indent=0] ---- [cols=1,3] <1> -\include::{snippets}index/links.adoc[] +\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. @@ -63,7 +63,7 @@ The title of a table can be specified using a line prefixed by a `.`: [source,adoc,indent=0] ---- .Links <1> -\include::{snippets}index/links.adoc[] +\include::{snippets}/index/links.adoc[] ---- <1> The table's title will be `Links`.