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

Polish "Add support for documenting request and response cookies"

Browse Source 
See gh-592
This commit is contained in:
Andy Wilkinson
2022-03-24 17:32:42 +00:00
parent f72a9f1067
commit d5522f5335
26 changed files with 480 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/src/docs/asciidoc/documenting-your-api.adoc
View File

@@ -988,40 +988,38 @@ Each contains a table describing the headers.
When documenting HTTP Headers, the test fails if a documented header is not found in the request or response.
[[documenting-your-api-http-cookies]]
=== HTTP Cookies
You can document the cookies in a request or response by using `requestCookies` and
`responseCookies`, respectively. The following examples show how to do so:
You can document the cookies in a request or response by using `requestCookies` and `responseCookies`, respectively.
The following examples show how to do so:
====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/HttpCookies.java[tags=cookies]
----
<1> Configure Spring REST Docs to produce a snippet describing the request's cookies.
Uses the static `requestCookies` method on
`org.springframework.restdocs.cookies.CookieDocumentation`.
<2> Document the `JSESSIONID` cookie. Uses the static `cookieWithName` method on
`org.springframework.restdocs.cookies.CookieDocumentation.
<3> Produce a snippet describing the response's cookies. Uses the static `responseCookies`
method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<4> Configure the request with an `JSESSIONID` and an additional cookie `logged_in`.
<1> Make a GET request with a `JSESSIONID` cookie.
<2> Configure Spring REST Docs to produce a snippet describing the request's cookies.
Uses the static `requestCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<3> Document the `JSESSIONID` cookie. Uses the static `cookieWithName` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<4> Produce a snippet describing the response's cookies.
Uses the static `responseCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/HttpCookies.java[tags=cookies]
----
<1> Configure Spring REST Docs to produce a snippet describing the request's cookies.
<1> Make a GET request with a `JSESSIONID` cookie.
<2> Configure Spring REST Docs to produce a snippet describing the request's cookies.
Uses the static `requestCookies` method on
`org.springframework.restdocs.cookies.CookieDocumentation`.
<2> Document the `JSESSIONID` cookie. Uses the static `cookieWithName` method on
`org.springframework.restdocs.cookies.CookieDocumentation.
<3> Produce a snippet describing the response's cookies. Uses the static `responseCookies`
method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<4> Configure the request with an `JSESSIONID` and an additional cookie `logged_in`.
<3> Document the `JSESSIONID` cookie.
Uses the static `cookieWithName` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<4> Produce a snippet describing the response's cookies.
Uses the static `responseCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
[source,java,indent=0,role="secondary"]
.REST Assured
@@ -1029,20 +1027,19 @@ include::{examples-dir}/com/example/webtestclient/HttpCookies.java[tags=cookies]
include::{examples-dir}/com/example/restassured/HttpCookies.java[tags=cookies]
----
<1> Configure Spring REST Docs to produce a snippet describing the request's cookies.
Uses the static `requestCookies` method on
`org.springframework.restdocs.cookies.CookieDocumentation`.
<2> Document the `JSESSIONID` cookie. Uses the static `cookieWithName` method on
`org.springframework.restdocs.cookies.CookieDocumentation.
<3> Produce a snippet describing the response's cookies. Uses the static `responseCookies`
method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<4> Configure the request with an `JSESSIONID` and an additional cookie `logged_in`.
====
Uses the static `requestCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<2> Document the `JSESSIONID` cookie.
Uses the static `cookieWithName` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<3> Produce a snippet describing the response's cookies.
Uses the static `responseCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
<4> Send a `JSESSIONID` cookie with the request.
The result is a snippet named `request-cookies.adoc` and a snippet named `response-cookies.adoc`.
Each contains a table describing the cookies.
When documenting HTTP Cookies, the test fails if a documented cookie is not found in the request or response.
The result is a snippet named `request-cookies.adoc` and a snippet named
`response-cookies.adoc`. Each contains a table describing the cookies.
When documenting HTTP Cookies, the test fails if a documented cookie is not found in
the request or response.
[[documenting-your-api-reusing-snippets]]
=== Reusing Snippets

2
docs/src/test/java/com/example/mockmvc/HttpCookies.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014-2016 the original author or authors.
* Copyright 2014-2022 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.

4
docs/src/test/java/com/example/restassured/HttpCookies.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014-2017 the original author or authors.
* Copyright 2014-2022 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.
@@ -29,7 +29,7 @@ public class HttpCookies {
private RequestSpecification spec;
public void cookies() throws Exception {
public void cookies() {
// tag::cookies[]
RestAssured.given(this.spec).filter(document("cookies", requestCookies(// <1>
cookieWithName("JSESSIONID").description("Saved session token")), // <2>

24
docs/src/test/java/com/example/webtestclient/HttpCookies.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2014-2017 the original author or authors.
* Copyright 2014-2022 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.
@@ -25,23 +25,17 @@ import static org.springframework.restdocs.webtestclient.WebTestClientRestDocume
public class HttpCookies {
// @formatter:off
private WebTestClient webTestClient;
public void cookies() throws Exception {
public void cookies() {
// 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"))));
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[]
}
}