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

Rework the API to improve readability and extensibility

Browse Source 
This commit updates the API to improve its extensibility and
readability.

SnippetWritingResultHandler has been replaced with a  more general
purpose Snippet interface. Snippets are now provided to the main
document method using varargs rather than the various with… methods
that were previously used. As a result a custom Snippet implementation
can now be used in exactly the same way as any of the built-in
snippets:

this.mockMvc.perform(get("/"))
        .andExpect(status().isOk())
        .andDo(document("index-example",
                links(
                        linkWithRel("notes").description("…"),
                        linkWithRel("tags").description("…")),
                responseFields(
                        fieldWithPath("_links").description("…")),
                yourCustomSnippet()));

Control of the snippets that are generated by default is now available
via RestDocumentationConfigurer:

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
        .apply(documentationConfiguration().snippets()
               .withDefaults(curlRequest(), yourCustomSnippet()))
        .build();

See gh-73
This commit is contained in:
Andy Wilkinson
2015-07-30 16:29:25 +01:00
parent aaf8aab77e
commit 0c8a71370b
67 changed files with 2326 additions and 1948 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -48,6 +48,26 @@ include::{examples-dir}/com/example/CustomEncoding.java[tags=custom-encoding]
[[configuration-default-snippets]]
=== Default snippets
Three snippets are produced by default:
- `curl-request`
- `http-request`
- `http-response`
This default configuration is applied by `RestDocumentationConfigurer`. You can use its
API to change the configuration. For example, to only produce the `curl-request` snippet
by default:
[source,java,indent=0]
----
include::{examples-dir}/com/example/CustomDefaultSnippetsConfiguration.java[tags=custom-default-snippets]
----
[[configuration-output-directory]]
=== Snippet output directory

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

@@ -15,7 +15,8 @@ https://en.wikipedia.org/wiki/HATEOAS[Hypermedia-based] API:
----
include::{examples-dir}/com/example/Hypermedia.java[tag=links]
----
<1> Use `withLinks` is to describe the expected links.
<1> Produce a snippet describing the response's links. Uses the static `links` method on
`org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
<2> Expect a link whose rel is `alpha`. Uses the static `linkWithRel` method on
`org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
<3> Expect a link whose rel is `bravo`.
@@ -40,14 +41,14 @@ Two link formats are understood by default:
content type of the response is compatible with `application/hal+json`.
If you are using Atom or HAL-format links but with a different content type you can
provide one of the built-in `LinkExtractor` implementations to `withLinks`. For example:
provide one of the built-in `LinkExtractor` implementations to `links`. For example:
[source,java,indent=0]
----
include::{examples-dir}/com/example/Hypermedia.java[tag=explicit-extractor]
----
<1> Indicate that the links are in HAL format. Uses the static `halLinks` method on
`org.springframework.restdocs.hypermedia.LinkExtractors`.
`org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
If your API represents its links in a format other than Atom or HAL you can provide your
own implementation of the `LinkExtractor` interface to extract the links from the
@@ -176,13 +177,14 @@ include::{examples-dir}/com/example/Payload.java[tags=explicit-type]
[[documenting-your-api-query-parameters]]
=== Query parameters
A request's query parameters can be documented using `withQueryParameters`
A request's query parameters can be documented using `queryParameters`
[source,java,indent=0]
----
include::{examples-dir}/com/example/QueryParameters.java[tags=query-parameters]
----
<1> Use `withQueryParameters` to describe the query parameters.
<1> Produce a snippet describing the request's query parameters. Uses the static
`queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
<2> Document a parameter named `page`. Uses the static `parameterWithName` method on
`org.springframework.restdocs.request.RequestDocumentation`.
<3> Document a parameter named `per_page`.
@@ -199,14 +201,15 @@ is not found in the request.
[[documenting-your-api-path-parameters]]
=== Path parameters
A request's path parameters can be documented using `withPathParameters`
A request's path parameters can be documented using `pathParameters`
[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`.
<2> Use `withPathParameters` to describe the path parameters.
<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
`org.springframework.restdocs.request.RequestDocumentation`.
<4> Document a parameter named `latitude`.
@@ -244,6 +247,9 @@ documented
| Contains the HTTP response that was returned
|===
You can configure which snippets are produced by default. Please refer to the
<<configuration, configuration section>> for more information.
[[documentating-your-api-parameterized-output-directories]]

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

@@ -200,7 +200,7 @@ be included in the project's jar:
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<configuration>
<outputDirectory>
${project.build.outputDirectory}/static/docs
</outputDirectory>
@@ -245,7 +245,7 @@ The `MockMvc` instance is configured using a `RestDocumentationConfigurer`. An i
of this class can be obtained from the static `documentationConfiguration()` method on
`org.springframework.restdocs.RestDocumentation`. `RestDocumentationConfigurer` applies
sensible defaults and also provides an API for customizing the configuration. Refer to the
<<configuration, Configuration section>> for more information.
<<configuration, configuration section>> for more information.

29
docs/src/test/java/com/example/CustomDefaultSnippetsConfiguration.java Normal file
View File

@@ -0,0 +1,29 @@
package com.example;
import static org.springframework.restdocs.RestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.curl.CurlDocumentation.curlRequest;
import org.junit.Before;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
public class CustomDefaultSnippetsConfiguration {
@Autowired
private WebApplicationContext context;
private MockMvc mockMvc;
@Before
public void setUp() {
// tag::custom-default-snippets[]
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(documentationConfiguration().snippets()
.withDefaults(curlRequest()))
.build();
// end::custom-default-snippets[]
}
}

13
docs/src/test/java/com/example/Hypermedia.java
View File

@@ -20,7 +20,8 @@ import static org.springframework.restdocs.RestDocumentation.document;
import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
import static org.springframework.restdocs.hypermedia.LinkExtractors.halLinks;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.halLinks;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
@@ -29,13 +30,13 @@ public class Hypermedia {
private MockMvc mockMvc;
public void links() throws Exception {
public void defaultExtractor() throws Exception {
// tag::links[]
this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("index").withLinks( // <1>
.andDo(document("index", links( // <1>
linkWithRel("alpha").description("Link to the alpha resource"), // <2>
linkWithRel("bravo").description("Link to the bravo resource"))); // <3>
linkWithRel("bravo").description("Link to the bravo resource")))); // <3>
// end::links[]
}
@@ -43,9 +44,9 @@ public class Hypermedia {
this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
//tag::explicit-extractor[]
.andDo(document("index").withLinks(halLinks(), // <1>
.andDo(document("index", links(halLinks(), // <1>
linkWithRel("alpha").description("Link to the alpha resource"),
linkWithRel("bravo").description("Link to the bravo resource")));
linkWithRel("bravo").description("Link to the bravo resource"))));
// end::explicit-extractor[]
}

7
docs/src/test/java/com/example/PathParameters.java
View File

@@ -18,6 +18,7 @@ package com.example;
import static org.springframework.restdocs.RestDocumentation.document;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@@ -27,14 +28,14 @@ public class PathParameters {
private MockMvc mockMvc;
public void pathParameters() throws Exception {
public void pathParametersSnippet() throws Exception {
// tag::path-parameters[]
this.mockMvc.perform(get("/locations/{latitude}/{longitude}", 51.5072, 0.1275)) // <1>
.andExpect(status().isOk())
.andDo(document("locations").withPathParameters( // <2>
.andDo(document("locations", pathParameters( // <2>
parameterWithName("latitude").description("The location's latitude"), // <3>
parameterWithName("longitude").description("The location's longitude") // <4>
));
)));
// end::path-parameters[]
}

15
docs/src/test/java/com/example/Payload.java
View File

@@ -18,6 +18,8 @@ package com.example;
import static org.springframework.restdocs.RestDocumentation.document;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
@@ -26,7 +28,6 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
import org.springframework.http.MediaType;
import org.springframework.restdocs.payload.FieldType;
import org.springframework.restdocs.snippet.Attributes;
import org.springframework.test.web.servlet.MockMvc;
public class Payload {
@@ -37,9 +38,9 @@ private MockMvc mockMvc;
// tag::response[]
this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("index").withResponseFields( // <1>
.andDo(document("index", responseFields( // <1>
fieldWithPath("contact").description("The user's contact details"), // <2>
fieldWithPath("contact.email").description("The user's email address"))); // <3>
fieldWithPath("contact.email").description("The user's email address")))); // <3>
// end::response[]
}
@@ -47,11 +48,11 @@ private MockMvc mockMvc;
this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
// tag::explicit-type[]
.andDo(document("index").withResponseFields(
.andDo(document("index", responseFields(
fieldWithPath("contact.email")
.type(FieldType.STRING) // <1>
.optional()
.description("The user's email address")));
.description("The user's email address"))));
// end::explicit-type[]
}
@@ -59,7 +60,7 @@ private MockMvc mockMvc;
this.mockMvc.perform(post("/users/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
// tag::constraints[]
.andDo(document("create-user").withRequestFields(
.andDo(document("create-user", requestFields(
attributes(
key("title").value("Fields for user creation")), // <1>
fieldWithPath("name")
@@ -69,7 +70,7 @@ private MockMvc mockMvc;
fieldWithPath("email")
.description("The user's email address")
.attributes(
key("constraints").value("Must be a valid email address")))); // <3>
key("constraints").value("Must be a valid email address"))))); // <3>
// end::constraints[]
}

7
docs/src/test/java/com/example/QueryParameters.java
View File

@@ -18,6 +18,7 @@ package com.example;
import static org.springframework.restdocs.RestDocumentation.document;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@@ -27,14 +28,14 @@ public class QueryParameters {
private MockMvc mockMvc;
public void queryParameters() throws Exception {
public void queryParametersSnippet() throws Exception {
// tag::query-parameters[]
this.mockMvc.perform(get("/users?page=2&per_page=100"))
.andExpect(status().isOk())
.andDo(document("users").withQueryParameters( // <1>
.andDo(document("users", queryParameters( // <1>
parameterWithName("page").description("The page to retrieve"), // <2>
parameterWithName("per_page").description("Entries per page") // <3>
));
)));
// end::query-parameters[]
}