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

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[]
}