3579b34a77
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
78 lines
3.0 KiB
Java
78 lines
3.0 KiB
Java
/*
|
|
* Copyright 2014-2015 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.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
package com.example;
|
|
|
|
import static org.springframework.restdocs.RestDocumentation.document;
|
|
import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
|
|
import static org.springframework.restdocs.RestDocumentationRequestBuilders.post;
|
|
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.test.web.servlet.result.MockMvcResultMatchers.status;
|
|
|
|
import org.springframework.http.MediaType;
|
|
import org.springframework.restdocs.payload.JsonFieldType;
|
|
import org.springframework.test.web.servlet.MockMvc;
|
|
|
|
public class Payload {
|
|
|
|
private MockMvc mockMvc;
|
|
|
|
public void response() throws Exception {
|
|
// tag::response[]
|
|
this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
|
|
.andExpect(status().isOk())
|
|
.andDo(document("index", responseFields( // <1>
|
|
fieldWithPath("contact").description("The user's contact details"), // <2>
|
|
fieldWithPath("contact.email").description("The user's email address")))); // <3>
|
|
// end::response[]
|
|
}
|
|
|
|
public void explicitType() throws Exception {
|
|
this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
|
|
.andExpect(status().isOk())
|
|
// tag::explicit-type[]
|
|
.andDo(document("index", responseFields(
|
|
fieldWithPath("contact.email")
|
|
.type(JsonFieldType.STRING) // <1>
|
|
.optional()
|
|
.description("The user's email address"))));
|
|
// end::explicit-type[]
|
|
}
|
|
|
|
public void constraints() throws Exception {
|
|
this.mockMvc.perform(post("/users/").accept(MediaType.APPLICATION_JSON))
|
|
.andExpect(status().isOk())
|
|
// tag::constraints[]
|
|
.andDo(document("create-user", requestFields(
|
|
attributes(
|
|
key("title").value("Fields for user creation")), // <1>
|
|
fieldWithPath("name")
|
|
.description("The user's name")
|
|
.attributes(
|
|
key("constraints").value("Must not be null. Must not be empty")), // <2>
|
|
fieldWithPath("email")
|
|
.description("The user's email address")
|
|
.attributes(
|
|
key("constraints").value("Must be a valid email address"))))); // <3>
|
|
// end::constraints[]
|
|
}
|
|
|
|
}
|