-
Notifications
You must be signed in to change notification settings - Fork 735
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add support for documenting request and response cookies
See gh-592
- Loading branch information
1 parent
15980d7
commit f72a9f1
Showing
38 changed files
with
1,572 additions
and
17 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
/* | ||
* 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. | ||
* You may obtain a copy of the License at | ||
* | ||
* https://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.mockmvc; | ||
|
||
import jakarta.servlet.http.Cookie; | ||
|
||
import org.springframework.test.web.servlet.MockMvc; | ||
|
||
import static org.springframework.restdocs.cookies.CookieDocumentation.cookieWithName; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.requestCookies; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.responseCookies; | ||
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document; | ||
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get; | ||
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; | ||
|
||
public class HttpCookies { | ||
|
||
private MockMvc mockMvc; | ||
|
||
public void cookies() throws Exception { | ||
// tag::cookies[] | ||
this.mockMvc.perform(get("/").cookie(new Cookie("JSESSIONID", "ACBCDFD0FF93D5BB"))) // <1> | ||
.andExpect(status().isOk()).andDo(document("cookies", requestCookies(// <2> | ||
cookieWithName("JSESSIONID").description("Session token")), // <3> | ||
responseCookies(// <4> | ||
cookieWithName("JSESSIONID").description("Updated session token"), | ||
cookieWithName("logged_in") | ||
.description("Set to true if the user is currently logged in")))); | ||
// end::cookies[] | ||
} | ||
|
||
} |
44 changes: 44 additions & 0 deletions
44
docs/src/test/java/com/example/restassured/HttpCookies.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
/* | ||
* Copyright 2014-2017 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 | ||
* | ||
* https://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.restassured; | ||
|
||
import io.restassured.RestAssured; | ||
import io.restassured.specification.RequestSpecification; | ||
|
||
import static org.hamcrest.CoreMatchers.is; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.cookieWithName; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.requestCookies; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.responseCookies; | ||
import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document; | ||
|
||
public class HttpCookies { | ||
|
||
private RequestSpecification spec; | ||
|
||
public void cookies() throws Exception { | ||
// tag::cookies[] | ||
RestAssured.given(this.spec).filter(document("cookies", requestCookies(// <1> | ||
cookieWithName("JSESSIONID").description("Saved session token")), // <2> | ||
responseCookies(// <3> | ||
cookieWithName("logged_in").description("If user is logged in"), | ||
cookieWithName("JSESSIONID").description("Updated session token")))) | ||
.cookie("JSESSIONID", "ACBCDFD0FF93D5BB") // <4> | ||
.when().get("/people").then().assertThat().statusCode(is(200)); | ||
// end::cookies[] | ||
} | ||
|
||
} |
47 changes: 47 additions & 0 deletions
47
docs/src/test/java/com/example/webtestclient/HttpCookies.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
/* | ||
* Copyright 2014-2017 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 | ||
* | ||
* https://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.webtestclient; | ||
|
||
import org.springframework.test.web.reactive.server.WebTestClient; | ||
|
||
import static org.springframework.restdocs.cookies.CookieDocumentation.cookieWithName; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.requestCookies; | ||
import static org.springframework.restdocs.cookies.CookieDocumentation.responseCookies; | ||
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document; | ||
|
||
public class HttpCookies { | ||
|
||
// @formatter:off | ||
|
||
private WebTestClient webTestClient; | ||
|
||
public void cookies() throws Exception { | ||
// tag::cookies[] | ||
this.webTestClient | ||
.get().uri("/people").cookie("JSESSIONID", "ACBCDFD0FF93D5BB=") // <1> | ||
.exchange().expectStatus().isOk().expectBody() | ||
.consumeWith(document("cookies", | ||
requestCookies(// <2> | ||
cookieWithName("JSESSIONID").description("Session token")), // <3> | ||
responseCookies(// <4> | ||
cookieWithName("JSESSIONID") | ||
.description("Updated session token"), | ||
cookieWithName("logged_in") | ||
.description("User is logged in")))); | ||
// end::cookies[] | ||
} | ||
} |
145 changes: 145 additions & 0 deletions
145
...tdocs-core/src/main/java/org/springframework/restdocs/cookies/AbstractCookiesSnippet.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,145 @@ | ||
/* | ||
* Copyright 2014-2017 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 | ||
* | ||
* https://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 org.springframework.restdocs.cookies; | ||
|
||
import java.util.ArrayList; | ||
import java.util.HashMap; | ||
import java.util.List; | ||
import java.util.Map; | ||
import java.util.Set; | ||
|
||
import org.springframework.restdocs.operation.Operation; | ||
import org.springframework.restdocs.snippet.SnippetException; | ||
import org.springframework.restdocs.snippet.TemplatedSnippet; | ||
import org.springframework.util.Assert; | ||
|
||
/** | ||
* Abstract {@link TemplatedSnippet} subclass that provides a base for snippets that | ||
* document a RESTful resource's request or response cookies. | ||
* | ||
* @author Andreas Evers | ||
* @author Clyde Stubbs | ||
* @since 2.1 | ||
*/ | ||
public abstract class AbstractCookiesSnippet extends TemplatedSnippet { | ||
|
||
private List<CookieDescriptor> cookieDescriptors; | ||
|
||
protected final boolean ignoreUndocumentedCookies; | ||
|
||
private String type; | ||
|
||
/** | ||
* Creates a new {@code AbstractCookiesSnippet} that will produce a snippet named | ||
* {@code <type>-cookies}. The cookies will be documented using the given | ||
* {@code descriptors} and the given {@code attributes} will be included in the model | ||
* during template rendering. | ||
* @param type the type of the cookies | ||
* @param descriptors the cookie descriptors | ||
* @param attributes the additional attributes | ||
* @param ignoreUndocumentedCookies whether undocumented cookies should be ignored | ||
*/ | ||
protected AbstractCookiesSnippet(String type, List<CookieDescriptor> descriptors, Map<String, Object> attributes, | ||
boolean ignoreUndocumentedCookies) { | ||
super(type + "-cookies", attributes); | ||
for (CookieDescriptor descriptor : descriptors) { | ||
Assert.notNull(descriptor.getName(), "The name of the cookie must not be null"); | ||
if (!descriptor.isIgnored()) { | ||
Assert.notNull(descriptor.getDescription(), "The description of the cookie must not be null"); | ||
} | ||
} | ||
this.cookieDescriptors = descriptors; | ||
this.type = type; | ||
this.ignoreUndocumentedCookies = ignoreUndocumentedCookies; | ||
} | ||
|
||
@Override | ||
protected Map<String, Object> createModel(Operation operation) { | ||
validateCookieDocumentation(operation); | ||
|
||
Map<String, Object> model = new HashMap<>(); | ||
List<Map<String, Object>> cookies = new ArrayList<>(); | ||
model.put("cookies", cookies); | ||
for (CookieDescriptor descriptor : this.cookieDescriptors) { | ||
cookies.add(createModelForDescriptor(descriptor)); | ||
} | ||
return model; | ||
} | ||
|
||
private void validateCookieDocumentation(Operation operation) { | ||
List<CookieDescriptor> missingCookies = findMissingCookies(operation); | ||
if (!missingCookies.isEmpty()) { | ||
List<String> names = new ArrayList<>(); | ||
for (CookieDescriptor cookieDescriptor : missingCookies) { | ||
names.add(cookieDescriptor.getName()); | ||
} | ||
throw new SnippetException( | ||
"Cookies with the following names were not found" + " in the " + this.type + ": " + names); | ||
} | ||
} | ||
|
||
/** | ||
* Finds the cookies that are missing from the operation. A cookie is missing if it is | ||
* described by one of the {@code cookieDescriptors} but is not present in the | ||
* operation. | ||
* @param operation the operation | ||
* @return descriptors for the cookies that are missing from the operation | ||
*/ | ||
protected List<CookieDescriptor> findMissingCookies(Operation operation) { | ||
List<CookieDescriptor> missingCookies = new ArrayList<>(); | ||
Set<String> actualCookies = extractActualCookies(operation); | ||
for (CookieDescriptor cookieDescriptor : this.cookieDescriptors) { | ||
if (!cookieDescriptor.isOptional() && !actualCookies.contains(cookieDescriptor.getName())) { | ||
missingCookies.add(cookieDescriptor); | ||
} | ||
} | ||
|
||
return missingCookies; | ||
} | ||
|
||
/** | ||
* Extracts the names of the cookies from the request or response of the given | ||
* {@code operation}. | ||
* @param operation the operation | ||
* @return the cookie names | ||
*/ | ||
protected abstract Set<String> extractActualCookies(Operation operation); | ||
|
||
/** | ||
* Returns the list of {@link CookieDescriptor CookieDescriptors} that will be used to | ||
* generate the documentation. | ||
* @return the cookie descriptors | ||
*/ | ||
protected final List<CookieDescriptor> getCookieDescriptors() { | ||
return this.cookieDescriptors; | ||
} | ||
|
||
/** | ||
* Returns a model for the given {@code descriptor}. | ||
* @param descriptor the descriptor | ||
* @return the model | ||
*/ | ||
protected Map<String, Object> createModelForDescriptor(CookieDescriptor descriptor) { | ||
Map<String, Object> model = new HashMap<>(); | ||
model.put("name", descriptor.getName()); | ||
model.put("description", descriptor.getDescription()); | ||
model.put("optional", descriptor.isOptional()); | ||
model.putAll(descriptor.getAttributes()); | ||
return model; | ||
} | ||
|
||
} |
Oops, something went wrong.