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

Polish documentation

Browse Source 
Closes gh-98
This commit is contained in:
izeye
2015-07-26 21:42:38 +09:00
committed by Andy Wilkinson
parent b1a6840b52
commit 6f4fe4ea64
6 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

2
docs/src/docs/asciidoc/customizing-responses.adoc
View File

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

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

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

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

@@ -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.
</build>
----
<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:
</executions>
</plugin>
----
<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

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

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