This commit splits Spring REST Docs into two projects –
spring-restdocs-core and spring-restdocs-mockmvc.
spring-restdocs-core contains the vast majority of the code but does not
depend on a specific test framework other than JUnit. The use of a
Spring Test TestExecutionListener has been replaced with a JUnit test
rule. The rule is declared once per test class and configured with
the output directory to which the generated snippets should be written.
This simplifies the implementation as thread local storage is no longer
required to transfer information about the test that’s running into
Spring REST Docs. Instead, this transfer is now handled by the new test
rule. It has also simplified the configuration as it’s no longer
necessary for users to provide a system property that configures the
output directory.
spring-restdocs-mockmvc contains code that’s specific to using Spring
REST Docs with Spring MVC Test’s MockMvc. This is currently the only
testing framework that’s supported, but it paves the way for adding
support for additional frameworks. REST Assured is one that users seem
particularly interested in (see gh-80 and gh-102).
Closes gh-107
Prior to this commit, MockMvc-classes were used throughout Spring REST
Docs. For example, each Snippet was called with an MvcResult. This
has proven problematic for a few reasons:
1. The MockMvc APIs aren't very amenable to modifying a request or
response before it's documented. This caused the existing support
for response modification to rely on CGLib proxies and method
interceptors. A similary complex solution for request modifiction
would also have been necessary.
2. Things are harder to reason about than they need to be as the
MockHttpServletRequest and MockHttpServletResponse classes
expose more than is required when generating API documentation.
3. Supporting other test frameworks, such as Rest Assured, is hard
This commit introduces a new Operation abstract that encapsulates
all of the information required to document the request that was sent
and the response that was received when performing an operation on a
RESTful service. The new abstraction uses types from Spring's Web
support, such as HttpHeaders, RequestMethod, and MediaType, but does
not rely on MockMvc.
Closes gh-108
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
