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

Update field snippets to no longer document whole subsection by default

Browse Source 
Previously, when a field was documented it would implicitly document
the whole subsection of the payload identified by that field. This
could lead to users inadvertently failing to document part of the
payload. Arguably, this was a bug as it violated REST Docs' principle
of producing accurate, detail documentation. However, fixing it
requires a breaking change as people may also be relying on this
behaviour. A balance needed to be struck so the fix is being made in
a minor release.

This commit introduces a new subsectionWithPath method which returns a
SubsectionDescriptor; a specialisation of FieldDescriptor. Users
that were intentionally relying on the old behaviour will have to
replace some usage of fieldWithPath with subsectionWithPath instead.
Users who were unintentionally relying on the old behaviour will have
to add some additional descriptors produced using fieldWithPath and
will receive more accurate documentation in return.

Closes gh-274
This commit is contained in:
Andy Wilkinson
2016-10-27 17:33:34 +01:00
parent 7bcfbd9e35
commit cbd96f301d
19 changed files with 830 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014-2015 the original author or authors.
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -28,6 +28,7 @@ import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuild
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@@ -59,7 +60,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
@SpringApplicationConfiguration(classes = RestNotesSpringDataRest.class)
@WebAppConfiguration
public class ApiDocumentation {
@Rule
public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
@@ -116,7 +117,7 @@ public class ApiDocumentation {
linkWithRel("tags").description("The <<resources-tags,Tags resource>>"),
linkWithRel("profile").description("The ALPS profile for the service")),
responseFields(
fieldWithPath("_links").description("<<resources-index-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources-index-links,Links>> to other resources"))));
}
@@ -137,8 +138,8 @@ public class ApiDocumentation {
linkWithRel("self").description("Canonical link for this resource"),
linkWithRel("profile").description("The ALPS profile for this resource")),
responseFields(
fieldWithPath("_embedded.notes").description("An array of <<resources-note, Note resources>>"),
fieldWithPath("_links").description("<<resources-tags-list-links, Links>> to other resources"))));
subsectionWithPath("_embedded.notes").description("An array of <<resources-note, Note resources>>"),
subsectionWithPath("_links").description("<<resources-tags-list-links, Links>> to other resources"))));
}
@Test
@@ -208,7 +209,7 @@ public class ApiDocumentation {
responseFields(
fieldWithPath("title").description("The title of the note"),
fieldWithPath("body").description("The body of the note"),
fieldWithPath("_links").description("<<resources-note-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources-note-links,Links>> to other resources"))));
}
@Test
@@ -227,8 +228,8 @@ public class ApiDocumentation {
linkWithRel("self").description("Canonical link for this resource"),
linkWithRel("profile").description("The ALPS profile for this resource")),
responseFields(
fieldWithPath("_embedded.tags").description("An array of <<resources-tag,Tag resources>>"),
fieldWithPath("_links").description("<<resources-tags-list-links, Links>> to other resources"))));
subsectionWithPath("_embedded.tags").description("An array of <<resources-tag,Tag resources>>"),
subsectionWithPath("_links").description("<<resources-tags-list-links, Links>> to other resources"))));
}
@Test
@@ -310,7 +311,7 @@ public class ApiDocumentation {
linkWithRel("notes").description("The <<resources-tagged-notes,notes>> that have this tag")),
responseFields(
fieldWithPath("name").description("The name of the tag"),
fieldWithPath("_links").description("<<resources-tag-links,Links>> to other resources"))));
subsectionWithPath("_links").description("<<resources-tag-links,Links>> to other resources"))));
}
@Test