记录 API (Documenting your API) _ Spring REST Docsversion 3.0.4-SNAPSHOT中文文档(官方文档中文翻译)|Spring 教程 —

API文档化

本节提供了有关使用 Spring REST Docs 来记录 API 的更多详细信息。spring-doc.cn

超媒体

Spring REST Docs 支持在基于超媒体的 API 中记录链接。以下示例显示了如何使用它：spring-doc.cn

MockMvc

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("index", links((1)
			linkWithRel("alpha").description("Link to the alpha resource"), (2)
			linkWithRel("bravo").description("Link to the bravo resource")))); (3)

1	配置 Spring REST 文档以生成描述响应链接的代码段。对使用 static 方法。`linksorg.springframework.restdocs.hypermedia.HypermediaDocumentation`
2	预期链接为。对使用 static 方法。`relalphalinkWithRelorg.springframework.restdocs.hypermedia.HypermediaDocumentation`
3	预期链接为。`relbravo`

WebTest客户端

this.webTestClient.get()
	.uri("/")
	.accept(MediaType.APPLICATION_JSON)
	.exchange()
	.expectStatus()
	.isOk()
	.expectBody()
	.consumeWith(document("index", links((1)
			linkWithRel("alpha").description("Link to the alpha resource"), (2)
			linkWithRel("bravo").description("Link to the bravo resource")))); (3)

1	配置 Spring REST 文档以生成描述响应链接的代码段。对使用 static 方法。`linksorg.springframework.restdocs.hypermedia.HypermediaDocumentation`
2	预期链接为。对使用 static 方法。`relalphalinkWithRelorg.springframework.restdocs.hypermedia.HypermediaDocumentation`
3	预期链接为。`relbravo`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("index", links((1)
			linkWithRel("alpha").description("Link to the alpha resource"), (2)
			linkWithRel("bravo").description("Link to the bravo resource")))) (3)
	.get("/")
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST 文档以生成描述响应链接的代码段。对使用 static 方法。`linksorg.springframework.restdocs.hypermedia.HypermediaDocumentation`
2	预期链接为。对使用 static 方法。`relalphalinkWithRelorg.springframework.restdocs.hypermedia.HypermediaDocumentation`
3	预期链接为。`relbravo`

结果是一个名为的代码段，其中包含一个描述资源链接的表。links.adocspring-doc.cn

如果响应中的链接具有，则可以从其描述符中省略描述，并使用。如果省略描述，并且链接没有，则会发生故障。titletitletitle

在记录链接时，如果在响应中找到未记录的链接，则测试将失败。同样，如果在响应中找不到记录的链接，并且该链接尚未标记为可选，则测试也会失败。spring-doc.cn

如果您不想记录链接，可以将其标记为已忽略。这样做可以防止它出现在生成的代码段中，同时避免上述失败。spring-doc.cn

您还可以在宽松模式下记录链接，其中任何未记录的链接都不会导致测试失败。为此，请使用上的方法。在记录您只想关注链接子集的特定方案时，这可能很有用。relaxedLinksorg.springframework.restdocs.hypermedia.HypermediaDocumentationspring-doc.cn

超媒体链接格式

默认情况下，可以理解两种链接格式：spring-doc.cn

Atom：链接应位于名为 . 当响应的内容类型与兼容时，默认情况下会使用此。linksapplication/jsonspring-doc.cn
HAL：链接应位于名为 . 当响应的内容类型与兼容时，默认情况下会使用此。_linksapplication/hal+jsonspring-doc.cn

如果您使用 Atom 或 HAL 格式的链接，但具有不同的内容类型，则可以为 . 以下示例说明如何执行此操作：LinkExtractorlinksspring-doc.cn

MockMvc

.andDo(document("index", links(halLinks(), (1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))));

1	指示链接采用 HAL 格式。对使用 static 方法。`halLinksorg.springframework.restdocs.hypermedia.HypermediaDocumentation`

WebTest客户端

.consumeWith(document("index", links(halLinks(), (1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))));

1	指示链接采用 HAL 格式。对使用 static 方法。`halLinksorg.springframework.restdocs.hypermedia.HypermediaDocumentation`

放心

.filter(document("index", links(halLinks(), (1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))))

1	指示链接采用 HAL 格式。对使用 static 方法。`halLinksorg.springframework.restdocs.hypermedia.HypermediaDocumentation`

如果您的 API 以 Atom 或 HAL 以外的格式表示其链接，则可以提供自己的接口实现，以便从响应中提取链接。LinkExtractorspring-doc.cn

忽略公共链接

您可能希望在概述部分中记录一次这些链接，然后在 API 文档的其余部分忽略它们，而不是记录每个响应通用的链接，例如和使用 HAL 时。为此，您可以基于对重用代码段的支持，将链接描述符添加到预配置为忽略某些链接的代码段中。以下示例显示了如何执行此操作：selfcuriesspring-doc.cn

public static LinksSnippet links(LinkDescriptor... descriptors) {
	return HypermediaDocumentation.links(linkWithRel("self").ignored().optional(), linkWithRel("curies").ignored())
		.and(descriptors);
}

请求和响应负载

除了前面描述的特定于超媒体的支持之外，还提供了对请求和响应有效负载的一般文档的支持。spring-doc.cn

默认情况下， Spring REST Docs 会自动为请求正文和响应正文生成片段。这些代码段分别命名为和。request-body.adocresponse-body.adocspring-doc.cn

请求和响应字段

为了提供更详细的请求或响应有效负载文档，提供了对记录有效负载字段的支持。spring-doc.cn

请考虑以下有效负载：spring-doc.cn

{
	"contact": {
		"name": "Jane Doe",
		"email": "[email protected]"
	}
}

您可以按如下方式记录上一个示例的字段：spring-doc.cn

MockMvc

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("index", responseFields((1)
			fieldWithPath("contact.email").description("The user's email address"), (2)
			fieldWithPath("contact.name").description("The user's name")))); (3)

1	配置 Spring REST 文档以生成描述响应有效负载中字段的代码段。要记录请求，您可以使用 . 两者都是上的静态方法。`requestFieldsorg.springframework.restdocs.payload.PayloadDocumentation`
2	期望一个路径为 . 对使用 static 方法。`contact.emailfieldWithPathorg.springframework.restdocs.payload.PayloadDocumentation`
3	期望一个路径为 .`contact.name`

WebTest客户端

this.webTestClient.get().uri("user/5").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("user",
		responseFields((1)
			fieldWithPath("contact.email").description("The user's email address"), (2)
			fieldWithPath("contact.name").description("The user's name")))); (3)

1	配置 Spring REST 文档以生成描述响应有效负载中字段的代码段。要记录请求，您可以使用 . 两者都是上的静态方法。`requestFieldsorg.springframework.restdocs.payload.PayloadDocumentation`
2	期望一个路径为 . 对使用 static 方法。`contact.emailfieldWithPathorg.springframework.restdocs.payload.PayloadDocumentation`
3	期望一个路径为 .`contact.name`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("user", responseFields((1)
			fieldWithPath("contact.name").description("The user's name"), (2)
			fieldWithPath("contact.email").description("The user's email address")))) (3)
	.when()
	.get("/user/5")
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST 文档以生成描述响应有效负载中字段的代码段。要记录请求，您可以使用 . 两者都是上的静态方法。`requestFieldsorg.springframework.restdocs.payload.PayloadDocumentation`
2	期望一个路径为 . 对使用 static 方法。`contact.emailfieldWithPathorg.springframework.restdocs.payload.PayloadDocumentation`
3	期望一个路径为 .`contact.name`

结果是一个代码段，其中包含一个描述字段的表。对于请求，此代码段名为。对于响应，此代码段名为。request-fields.adocresponse-fields.adocspring-doc.cn

记录字段时，如果在有效负载中找到未记录的字段，则测试将失败。同样，如果在有效负载中找不到记录的字段，并且该字段尚未标记为可选，则测试也会失败。spring-doc.cn

如果您不想为所有字段提供详细的文档，则可以记录有效负载的整个子部分。以下示例说明如何执行此操作：spring-doc.cn

MockMvc

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("index", responseFields((1)
			subsectionWithPath("contact").description("The user's contact details")))); (1)

1	使用 path 记录小节。现在也被视为已被记录在案。对使用 static 方法。`contactcontact.emailcontact.namesubsectionWithPathorg.springframework.restdocs.payload.PayloadDocumentation`

WebTest客户端

this.webTestClient.get().uri("user/5").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("user",
		responseFields(
			subsectionWithPath("contact").description("The user's contact details")))); (1)

1	使用 path 记录小节。现在也被视为已被记录在案。对使用 static 方法。`contactcontact.emailcontact.namesubsectionWithPathorg.springframework.restdocs.payload.PayloadDocumentation`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("user",
			responseFields(subsectionWithPath("contact").description("The user's contact details")))) (1)
	.when()
	.get("/user/5")
	.then()
	.assertThat()
	.statusCode(is(200));

1	使用 path 记录小节。现在也被视为已被记录在案。对使用 static 方法。`contactcontact.emailcontact.namesubsectionWithPathorg.springframework.restdocs.payload.PayloadDocumentation`

subsectionWithPath可用于提供有效负载特定部分的高级概述。然后，您可以为小节生成单独的、更详细的文档。请参阅记录请求或响应有效负载的子部分。spring-doc.cn

如果您根本不想记录字段或子部分，则可以将其标记为已忽略。这可以防止它出现在生成的代码段中，同时避免前面描述的失败。spring-doc.cn

您还可以在宽松模式下记录字段，其中任何未记录的字段都不会导致测试失败。为此，请使用上的和方法。在记录您只想关注负载子集的特定方案时，这可能很有用。relaxedRequestFieldsrelaxedResponseFieldsorg.springframework.restdocs.payload.PayloadDocumentationspring-doc.cn

默认情况下，Spring REST Docs 假定您正在记录的有效负载是 JSON。如果要记录 XML 有效负载，则请求或响应的内容类型必须与兼容。application/xml

JSON 有效负载中的字段

本节介绍如何使用 JSON 负载中的字段。spring-doc.cn

JSON 字段路径

JSON 字段路径使用点表示法或方括号表示法。点表示法使用 '.' 来分隔路径中的每个键（例如，）。方括号表示法将每个键括在方括号和单引号中（例如，）。在任一情况下，都用于标识数组。点表示法更简洁，但使用方括号表示法可以在键名称中使用（例如，）。两种不同的表示法可以在同一路径中使用（例如，）。a.b['a']['b'][].['a.b']a['b']spring-doc.cn

请考虑以下 JSON 有效负载：spring-doc.cn

{
	"a":{
		"b":[
			{
				"c":"one"
			},
			{
				"c":"two"
			},
			{
				"d":"three"
			}
		],
		"e.dot" : "four"
	}
}

在前面的 JSON 有效负载中，以下路径都存在：spring-doc.cn

路径值

路径	值
`a`spring-doc.cn	包含`b`spring-doc.cn
`a.b`spring-doc.cn	包含 3 个对象的数组spring-doc.cn
`['a']['b']`spring-doc.cn	包含 3 个对象的数组spring-doc.cn
`a['b']`spring-doc.cn	包含 3 个对象的数组spring-doc.cn
`['a'].b`spring-doc.cn	包含 3 个对象的数组spring-doc.cn
`a.b[]`spring-doc.cn	包含 3 个对象的数组spring-doc.cn
`a.b[].c`spring-doc.cn	包含字符串和`onetwo`spring-doc.cn
`a.b[].d`spring-doc.cn	字符串`three`spring-doc.cn
`a['e.dot']`spring-doc.cn	字符串`four`spring-doc.cn
`['a']['e.dot']`spring-doc.cn	字符串`four`spring-doc.cn

aspring-doc.cn

包含bspring-doc.cn

a.bspring-doc.cn

包含 3 个对象的数组spring-doc.cn

['a']['b']spring-doc.cn

包含 3 个对象的数组spring-doc.cn

a['b']spring-doc.cn

包含 3 个对象的数组spring-doc.cn

['a'].bspring-doc.cn

包含 3 个对象的数组spring-doc.cn

a.b[]spring-doc.cn

包含 3 个对象的数组spring-doc.cn

a.b[].cspring-doc.cn

包含字符串和onetwospring-doc.cn

a.b[].dspring-doc.cn

字符串threespring-doc.cn

a['e.dot']spring-doc.cn

字符串fourspring-doc.cn

['a']['e.dot']spring-doc.cn

字符串fourspring-doc.cn

您还可以记录在其根上使用数组的有效负载。该路径引用整个数组。然后，您可以使用方括号或点表示法来标识数组条目中的字段。例如，对应于在以下数组中找到的每个对象的字段：[][].ididspring-doc.cn

[
	{
		"id":1
	},
	{
		"id":2
	}
]

您可以用作通配符来匹配具有不同名称的字段。例如，可用于在以下 JSON 中记录每个用户的角色：*users.*.rolespring-doc.cn

{
	"users":{
		"ab12cd34":{
			"role": "Administrator"
		},
		"12ab34cd":{
			"role": "Guest"
		}
	}
}

JSON 字段类型

当一个字段被记录下来时， Spring REST Docs 会尝试通过检查有效负载来确定它的类型。支持七种不同的类型：spring-doc.cn

类型描述

类型	描述
`array`spring-doc.cn	该字段每次出现的值都是一个数组。spring-doc.cn
`boolean`spring-doc.cn	该字段每次出现的值都是一个布尔值（或）。`truefalse`spring-doc.cn
`object`spring-doc.cn	字段每次出现的值都是一个对象。spring-doc.cn
`number`spring-doc.cn	该字段每次出现的值都是一个数字。spring-doc.cn
`null`spring-doc.cn	该字段每次出现的值都是。`null`spring-doc.cn
`string`spring-doc.cn	该字段每次出现的值都是一个字符串。spring-doc.cn
`varies`spring-doc.cn	该字段在有效负载中多次出现，具有各种不同类型的负载。spring-doc.cn

arrayspring-doc.cn

该字段每次出现的值都是一个数组。spring-doc.cn

booleanspring-doc.cn

该字段每次出现的值都是一个布尔值（或）。truefalsespring-doc.cn

objectspring-doc.cn

字段每次出现的值都是一个对象。spring-doc.cn

numberspring-doc.cn

该字段每次出现的值都是一个数字。spring-doc.cn

nullspring-doc.cn

该字段每次出现的值都是。nullspring-doc.cn

stringspring-doc.cn

该字段每次出现的值都是一个字符串。spring-doc.cn

variesspring-doc.cn

该字段在有效负载中多次出现，具有各种不同类型的负载。spring-doc.cn

您还可以使用 on 上的方法显式设置类型。所提供方法的结果用于文档中。通常，使用 by 枚举的值之一。以下示例说明如何执行此操作：type(Object)FieldDescriptortoStringObjectJsonFieldTypespring-doc.cn

MockMvc

.andDo(document("index", responseFields(fieldWithPath("contact.email").type(JsonFieldType.STRING) (1)
	.description("The user's email address"))));

1	将字段的类型设置为。`String`

WebTest客户端

.consumeWith(document("user",
	responseFields(
		fieldWithPath("contact.email")
			.type(JsonFieldType.STRING) (1)
			.description("The user's email address"))));

1	将字段的类型设置为。`String`

放心

.filter(document("user", responseFields(fieldWithPath("contact.email").type(JsonFieldType.STRING) (1)
	.description("The user's email address"))))

1	将字段的类型设置为。`String`

XML 负载

本节介绍如何使用 XML 有效负载。spring-doc.cn

XML 字段路径

XML 字段路径使用 XPath 进行描述。用于下降到子节点。/spring-doc.cn

XML 字段类型

在记录 XML 负载时，必须使用上的方法为字段提供类型。提供的类型的 method 的结果在文档中使用。type(Object)FieldDescriptortoStringspring-doc.cn

重用字段描述符

除了对重用代码段的一般支持之外，请求和响应代码段还允许使用路径前缀配置其他描述符。这允许创建请求或响应有效负载的重复部分的描述符一次，然后重复使用。spring-doc.cn

考虑一个返回一本书的终端节点：spring-doc.cn

{
	"title": "Pride and Prejudice",
	"author": "Jane Austen"
}

的路径分别为和和。titleauthortitleauthorspring-doc.cn

现在考虑一个返回书籍数组的终端节点：spring-doc.cn

[{
	"title": "Pride and Prejudice",
	"author": "Jane Austen"
},
{
	"title": "To Kill a Mockingbird",
	"author": "Harper Lee"
}]

的路径分别为和和。单个 book 和 array of books 之间的唯一区别是字段的路径现在有一个前缀。titleauthor[].title[].author[].spring-doc.cn

您可以创建记录书籍的描述符，如下所示：spring-doc.cn

FieldDescriptor[] book = new FieldDescriptor[] { fieldWithPath("title").description("Title of the book"),
		fieldWithPath("author").description("Author of the book") };

然后，您可以使用它们来记录一本图书，如下所示：spring-doc.cn

MockMvc

this.mockMvc.perform(get("/books/1").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("book", responseFields(book))); (1)

1	记录和使用现有描述符`titleauthor`

WebTest客户端

this.webTestClient.get().uri("/books/1").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("book",
		responseFields(book))); (1)

1	记录和使用现有描述符`titleauthor`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("book", responseFields(book))) (1)
	.when()
	.get("/books/1")
	.then()
	.assertThat()
	.statusCode(is(200));

1	记录和使用现有描述符`titleauthor`

您还可以使用描述符来记录书籍数组，如下所示：spring-doc.cn

MockMvc

this.mockMvc.perform(get("/books").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("book", responseFields(fieldWithPath("[]").description("An array of books")) (1)
		.andWithPrefix("[].", book))); (2)

1	记录数组。
2	Document 并使用前缀为`[].title[].author[].`

WebTest客户端

this.webTestClient.get().uri("/books").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("books",
		responseFields(
			fieldWithPath("[]")
				.description("An array of books")) (1)
				.andWithPrefix("[].", book))); (2)

1	记录数组。
2	Document 并使用前缀为`[].title[].author[].`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("books", responseFields(fieldWithPath("[]").description("An array of books")) (1)
		.andWithPrefix("[].", book))) (2)
	.when()
	.get("/books")
	.then()
	.assertThat()
	.statusCode(is(200));

1	记录数组。
2	Document 并使用前缀为`[].title[].author[].`

记录 Request 或 Response Payload 的 Subsection

如果有效负载很大或结构复杂，则记录有效负载的各个部分可能很有用。 REST Docs 允许您通过提取有效负载的子部分，然后对其进行记录来实现此目的。spring-doc.cn

记录请求或响应正文的子部分

请考虑以下 JSON 响应正文：spring-doc.cn

{
	"weather": {
		"wind": {
			"speed": 15.3,
			"direction": 287.0
		},
		"temperature": {
			"high": 21.2,
			"low": 14.8
		}
	}
}

您可以生成一个代码段来记录对象，如下所示：temperaturespring-doc.cn

MockMvc

this.mockMvc.perform(get("/locations/1").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("location", responseBody(beneathPath("weather.temperature")))); (1)

1	生成包含响应正文的子部分的代码片段。对使用 static 和方法。要为请求正文生成代码段，您可以使用 .`responseBodybeneathPathorg.springframework.restdocs.payload.PayloadDocumentationrequestBodyresponseBody`

WebTest客户端

this.webTestClient.get().uri("/locations/1").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("temperature",
		responseBody(beneathPath("weather.temperature")))); (1)

1	生成包含响应正文的子部分的代码片段。对使用 static 和方法。要为请求正文生成代码段，您可以使用 .`responseBodybeneathPathorg.springframework.restdocs.payload.PayloadDocumentationrequestBodyresponseBody`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("location", responseBody(beneathPath("weather.temperature")))) (1)
	.when()
	.get("/locations/1")
	.then()
	.assertThat()
	.statusCode(is(200));

1	生成包含响应正文的子部分的代码片段。对使用 static 和方法。要为请求正文生成代码段，您可以使用 .`responseBodybeneathPathorg.springframework.restdocs.payload.PayloadDocumentationrequestBodyresponseBody`

结果是一个包含以下内容的代码段：spring-doc.cn

{
	"temperature": {
		"high": 21.2,
		"low": 14.8
	}
}

为了使代码段的名称与众不同，将包含该小节的标识符。默认情况下，此标识符为 . 例如，前面的代码会生成一个名为 . 您可以使用该方法自定义标识符，如下所示：beneath-${path}response-body-beneath-weather.temperature.adocwithSubsectionId(String)spring-doc.cn

responseBody(beneathPath("weather.temperature").withSubsectionId("temp"));

结果是一个名为的代码段。request-body-temp.adocspring-doc.cn

记录请求或响应的 subsection 的字段

除了记录请求或响应正文的子部分外，您还可以记录特定子部分中的字段。您可以生成一个代码段来记录对象的字段（和），如下所示：temperaturehighlowspring-doc.cn

MockMvc

this.mockMvc.perform(get("/locations/1").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("location", responseFields(beneathPath("weather.temperature"), (1)
			fieldWithPath("high").description("The forecast high in degrees celcius"), (2)
			fieldWithPath("low").description("The forecast low in degrees celcius"))));

1	生成一个代码段，描述 path 下方响应有效负载子部分中的字段。对使用 static 方法。`weather.temperaturebeneathPathorg.springframework.restdocs.payload.PayloadDocumentation`
2	记录和字段。`highlow`

WebTest客户端

this.webTestClient.get().uri("/locations/1").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("temperature",
		responseFields(beneathPath("weather.temperature"), (1)
			fieldWithPath("high").description("The forecast high in degrees celcius"), (2)
			fieldWithPath("low").description("The forecast low in degrees celcius"))));

1	生成一个代码段，描述 path 下方响应有效负载子部分中的字段。对使用 static 方法。`weather.temperaturebeneathPathorg.springframework.restdocs.payload.PayloadDocumentation`
2	记录和字段。`highlow`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("location", responseFields(beneathPath("weather.temperature"), (1)
			fieldWithPath("high").description("The forecast high in degrees celcius"), (2)
			fieldWithPath("low").description("The forecast low in degrees celcius"))))
	.when()
	.get("/locations/1")
	.then()
	.assertThat()
	.statusCode(is(200));

1	生成一个代码段，描述响应有效负载的子部分中的字段在路径下。对使用 static 方法。`weather.temperaturebeneathPathorg.springframework.restdocs.payload.PayloadDocumentation`
2	记录和字段。`highlow`

结果是一个代码片段，其中包含一个描述的和字段的表。为了使代码段的名称与众不同，将包含该小节的标识符。默认情况下，此标识符为 . 例如，前面的代码会生成一个名为 .highlowweather.temperaturebeneath-${path}response-fields-beneath-weather.temperature.adocspring-doc.cn

查询参数

您可以使用记录请求的查询参数。以下示例说明如何执行此操作：queryParametersspring-doc.cn

MockMvc

this.mockMvc.perform(get("/users?page=2&per_page=100")) (1)
	.andExpect(status().isOk())
	.andDo(document("users", queryParameters((2)
			parameterWithName("page").description("The page to retrieve"), (3)
			parameterWithName("per_page").description("Entries per page") (4)
	)));

1	使用查询字符串中的两个参数和、执行请求。查询参数应包含在 URL 中，如此处所示，或使用请求生成器的 or 方法指定。应避免使用 and 方法，因为参数的来源是模棱两可的。`GETpageper_pagequeryParamqueryParamsparamparams`
2	配置 Spring REST Docs 以生成描述请求的查询参数的代码段。对使用 static 方法。`queryParametersorg.springframework.restdocs.request.RequestDocumentation`
3	记录查询参数。对使用 static 方法。`pageparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
4	记录查询参数。`per_page`

WebTest客户端

this.webTestClient.get().uri("/users?page=2&per_page=100") (1)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("users", queryParameters((2)
			parameterWithName("page").description("The page to retrieve"), (3)
			parameterWithName("per_page").description("Entries per page") (4)
	)));

1	使用查询字符串中的两个参数和、执行请求。`GETpageper_page`
2	配置 Spring REST Docs 以生成描述请求的查询参数的代码段。对使用 static 方法。`queryParametersorg.springframework.restdocs.request.RequestDocumentation`
3	记录参数。对使用 static 方法。`pageparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
4	记录参数。`per_page`

放心

RestAssured.given(this.spec)
	.filter(document("users", queryParameters((1)
			parameterWithName("page").description("The page to retrieve"), (2)
			parameterWithName("per_page").description("Entries per page")))) (3)
	.when()
	.get("/users?page=2&per_page=100") (4)
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST Docs 以生成描述请求的查询参数的代码段。对使用 static 方法。`queryParametersorg.springframework.restdocs.request.RequestDocumentation`
2	记录参数。对使用 static 方法。`pageparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
3	记录参数。`per_page`
4	使用查询字符串中的两个参数和、执行请求。`GETpageper_page`

在记录查询参数时，如果在请求的查询字符串中使用了未记录的查询参数，则测试将失败。同样，如果在请求的查询字符串中找不到记录的查询参数，并且该参数尚未标记为可选，则测试也会失败。spring-doc.cn

如果您不想记录查询参数，可以将其标记为 ignored。这可以防止它出现在生成的代码片段中，同时避免上述失败。spring-doc.cn

您还可以在宽松模式下记录查询参数，其中任何未记录的参数都不会导致测试失败。为此，请使用上的方法。在记录您只想关注查询参数子集的特定方案时，这可能很有用。relaxedQueryParametersorg.springframework.restdocs.request.RequestDocumentationspring-doc.cn

表单参数

您可以使用 . 以下示例说明如何执行此操作：formParametersspring-doc.cn

MockMvc

this.mockMvc.perform(post("/users").param("username", "Tester")) (1)
	.andExpect(status().isCreated())
	.andDo(document("create-user", formParameters((2)
			parameterWithName("username").description("The user's username") (3)
	)));

1	使用单个表单参数 .`POSTusername`
2	配置 Spring REST Docs 以生成描述请求的表单参数的片段。对使用 static 方法。`formParametersorg.springframework.restdocs.request.RequestDocumentation`
3	记录参数。对使用 static 方法。`usernameparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`

WebTest客户端

MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
formData.add("username", "Tester");
this.webTestClient.post().uri("/users").body(BodyInserters.fromFormData(formData)) (1)
		.exchange().expectStatus().isCreated().expectBody()
		.consumeWith(document("create-user", formParameters((2)
				parameterWithName("username").description("The user's username") (3)
		)));

1	使用单个表单参数 .`POSTusername`
2	配置 Spring REST Docs 以生成描述请求的表单参数的片段。对使用 static 方法。`formParametersorg.springframework.restdocs.request.RequestDocumentation`
3	记录参数。对使用 static 方法。`usernameparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`

放心

RestAssured.given(this.spec)
	.filter(document("create-user", formParameters((1)
			parameterWithName("username").description("The user's username")))) (2)
	.formParam("username", "Tester")
	.when()
	.post("/users") (3)
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST Docs 以生成描述请求的表单参数的片段。对使用 static 方法。`formParametersorg.springframework.restdocs.request.RequestDocumentation`
2	记录参数。对使用 static 方法。`usernameparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
3	使用单个表单参数 .`POSTusername`

在所有情况下，结果都是一个名为的代码段，其中包含一个描述资源支持的表单参数的表。form-parameters.adocspring-doc.cn

在记录表单参数时，如果在请求正文中使用了未记录的表单参数，则测试将失败。同样，如果在请求正文中找不到记录的 form 参数，并且 form 参数尚未标记为可选，则测试也会失败。spring-doc.cn

如果您不想记录表单参数，可以将其标记为已忽略。这可以防止它出现在生成的代码片段中，同时避免上述失败。spring-doc.cn

您还可以在宽松模式下记录表单参数，其中任何未记录的参数都不会导致测试失败。为此，请使用上的方法。在记录您只想关注表单参数子集的特定方案时，这可能很有用。relaxedFormParametersorg.springframework.restdocs.request.RequestDocumentationspring-doc.cn

路径参数

您可以使用 . 以下示例说明如何执行此操作：pathParametersspring-doc.cn

MockMvc

this.mockMvc.perform(get("/locations/{latitude}/{longitude}", 51.5072, 0.1275)) (1)
	.andExpect(status().isOk())
	.andDo(document("locations", pathParameters((2)
			parameterWithName("latitude").description("The location's latitude"), (3)
			parameterWithName("longitude").description("The location's longitude") (4)
	)));

1	使用两个路径参数执行请求，并且 .`GETlatitudelongitude`
2	配置 Spring REST Docs 以生成描述请求的 path 参数的代码段。对使用 static 方法。`pathParametersorg.springframework.restdocs.request.RequestDocumentation`
3	记录名为的参数。对使用 static 方法。`latitudeparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
4	记录名为的参数。`longitude`

WebTest客户端

this.webTestClient.get().uri("/locations/{latitude}/{longitude}", 51.5072, 0.1275) (1)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("locations",
		pathParameters((2)
			parameterWithName("latitude").description("The location's latitude"), (3)
			parameterWithName("longitude").description("The location's longitude")))); (4)

1	使用两个路径参数执行请求，并且 .`GETlatitudelongitude`
2	配置 Spring REST Docs 以生成描述请求的 path 参数的代码段。对使用 static 方法。`pathParametersorg.springframework.restdocs.request.RequestDocumentation`
3	记录名为的参数。对使用 static 方法。`latitudeparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
4	记录名为的参数。`longitude`

放心

RestAssured.given(this.spec)
	.filter(document("locations", pathParameters((1)
			parameterWithName("latitude").description("The location's latitude"), (2)
			parameterWithName("longitude").description("The location's longitude")))) (3)
	.when()
	.get("/locations/{latitude}/{longitude}", 51.5072, 0.1275) (4)
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST Docs 以生成描述请求的 path 参数的代码段。对使用 static 方法。`pathParametersorg.springframework.restdocs.request.RequestDocumentation`
2	记录名为的参数。对使用 static 方法。`latitudeparameterWithNameorg.springframework.restdocs.request.RequestDocumentation`
3	记录名为的参数。`longitude`
4	使用两个路径参数执行请求，并且 .`GETlatitudelongitude`

结果是一个名为的代码段，其中包含一个表，该表描述资源支持的路径参数。path-parameters.adocspring-doc.cn

如果将 MockMvc 与 Spring Framework 6.1 或更早版本一起使用，要使路径参数可用于文档，则必须使用 on 而不是 .RestDocumentationRequestBuildersMockMvcRequestBuilders

在记录路径参数时，如果在请求中使用了未记录的路径参数，则测试将失败。同样，如果在请求中找不到记录的 path 参数，并且 path 参数尚未标记为可选，则测试也会失败。spring-doc.cn

您还可以在宽松模式下记录路径参数，其中任何未记录的参数都不会导致测试失败。为此，请使用上的方法。在记录您只想关注 path 参数子集的特定方案时，这可能很有用。relaxedPathParametersorg.springframework.restdocs.request.RequestDocumentationspring-doc.cn

如果您不想记录 path 参数，可以将其标记为已忽略。这样做可以防止它出现在生成的代码段中，同时避免前面描述的故障。spring-doc.cn

索取零件

可用于记录 multipart 请求的各部分。以下示例显示了如何执行此操作：requestPartsspring-doc.cn

MockMvc

this.mockMvc.perform(multipart("/upload").file("file", "example".getBytes())) (1)
	.andExpect(status().isOk())
	.andDo(document("upload", requestParts((2)
			partWithName("file").description("The file to upload")) (3)
	));

1	使用名为的单个部件执行请求。`POSTfile`
2	配置 Spring REST Docs 以生成描述请求部分的代码片段。对使用 static 方法。`requestPartsorg.springframework.restdocs.request.RequestDocumentation`
3	记录名为的部件。对使用 static 方法。`filepartWithNameorg.springframework.restdocs.request.RequestDocumentation`

WebTest客户端

MultiValueMap<String, Object> multipartData = new LinkedMultiValueMap<>();
multipartData.add("file", "example".getBytes());
this.webTestClient.post().uri("/upload").body(BodyInserters.fromMultipartData(multipartData)) (1)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("upload", requestParts((2)
		partWithName("file").description("The file to upload")) (3)
));

1	使用名为的单个部件执行请求。`POSTfile`
2	配置 Spring REST Docs 以生成描述请求部分的代码片段。对使用 static 方法。`requestPartsorg.springframework.restdocs.request.RequestDocumentation`
3	记录名为的部件。对使用 static 方法。`filepartWithNameorg.springframework.restdocs.request.RequestDocumentation`

放心

RestAssured.given(this.spec)
	.filter(document("users", requestParts((1)
			partWithName("file").description("The file to upload")))) (2)
	.multiPart("file", "example") (3)
	.when()
	.post("/upload") (4)
	.then()
	.statusCode(is(200));

1	配置 Spring REST Docs 以生成描述请求部分的代码片段。对使用 static 方法。`requestPartsorg.springframework.restdocs.request.RequestDocumentation`
2	记录名为的部件。对使用 static 方法。`filepartWithNameorg.springframework.restdocs.request.RequestDocumentation`
3	使用名为的部件配置请求。`file`
4	执行对的请求。`POST/upload`

结果是一个名为的代码段，其中包含一个表，该表描述资源支持的请求部分。request-parts.adocspring-doc.cn

在记录请求部分时，如果在请求中使用了未记录的部分，则测试将失败。同样，如果在请求中找不到记录的段，并且该段尚未标记为可选，则测试也会失败。spring-doc.cn

您还可以在宽松模式下记录请求部分，其中任何未记录的部分都不会导致测试失败。为此，请使用上的方法。在记录您只想关注请求部分子集的特定方案时，这可能很有用。relaxedRequestPartsorg.springframework.restdocs.request.RequestDocumentationspring-doc.cn

如果您不想记录请求部分，则可以将其标记为已忽略。这可以防止它出现在生成的代码段中，同时避免前面描述的失败。spring-doc.cn

请求部件有效负载

您可以采用与请求有效负载大致相同的方式记录请求部分的有效负载，并支持记录请求部分的正文及其字段。spring-doc.cn

记录请求部件的正文

您可以生成包含请求部分正文的代码段，如下所示：spring-doc.cn

MockMvc

MockMultipartFile image = new MockMultipartFile("image", "image.png", "image/png", "<<png data>>".getBytes());
MockMultipartFile metadata = new MockMultipartFile("metadata", "", "application/json",
		"{ \"version\": \"1.0\"}".getBytes());

this.mockMvc.perform(multipart("/images").file(image).file(metadata).accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("image-upload", requestPartBody("metadata"))); (1)

1	配置 Spring REST 文档以生成一个代码段，其中包含名为的请求部分的正文。对使用 static 方法。`metadatarequestPartBodyPayloadDocumentation`

WebTest客户端

MultiValueMap<String, Object> multipartData = new LinkedMultiValueMap<>();
Resource imageResource = new ByteArrayResource("<<png data>>".getBytes()) {

	@Override
	public String getFilename() {
		return "image.png";
	}

};
multipartData.add("image", imageResource);
multipartData.add("metadata", Collections.singletonMap("version",  "1.0"));

this.webTestClient.post().uri("/images").body(BodyInserters.fromMultipartData(multipartData))
	.accept(MediaType.APPLICATION_JSON).exchange()
	.expectStatus().isOk().expectBody()
	.consumeWith(document("image-upload",
			requestPartBody("metadata"))); (1)

1	配置 Spring REST 文档以生成一个代码段，其中包含名为的请求部分的正文。对使用 static 方法。`metadatarequestPartBodyPayloadDocumentation`

放心

Map<String, String> metadata = new HashMap<>();
metadata.put("version", "1.0");
RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("image-upload", requestPartBody("metadata"))) (1)
	.when()
	.multiPart("image", new File("image.png"), "image/png")
	.multiPart("metadata", metadata)
	.post("images")
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST 文档以生成一个代码段，其中包含名为的请求部分的正文。对使用 static 方法。`metadatarequestPartBodyPayloadDocumentation`

结果是包含部件主体的 named 代码段。例如，记录名为的部件会生成一个名为的代码段。request-part-${part-name}-body.adocmetadatarequest-part-metadata-body.adocspring-doc.cn

记录请求部分的字段

您可以采用与记录请求或响应的字段大致相同的方式记录请求部分的字段，如下所示：spring-doc.cn

MockMvc

MockMultipartFile image = new MockMultipartFile("image", "image.png", "image/png", "<<png data>>".getBytes());
MockMultipartFile metadata = new MockMultipartFile("metadata", "", "application/json",
		"{ \"version\": \"1.0\"}".getBytes());

this.mockMvc.perform(multipart("/images").file(image).file(metadata).accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("image-upload", requestPartFields("metadata", (1)
			fieldWithPath("version").description("The version of the image")))); (2)

1	配置 Spring REST 文档以生成一个代码段，用于描述名为的请求部分的有效负载中的字段。对使用 static 方法。`metadatarequestPartFieldsPayloadDocumentation`
2	期望一个路径为 . 对使用 static 方法。`versionfieldWithPathorg.springframework.restdocs.payload.PayloadDocumentation`

WebTest客户端

MultiValueMap<String, Object> multipartData = new LinkedMultiValueMap<>();
Resource imageResource = new ByteArrayResource("<<png data>>".getBytes()) {

	@Override
	public String getFilename() {
		return "image.png";
	}

};
multipartData.add("image", imageResource);
multipartData.add("metadata", Collections.singletonMap("version",  "1.0"));
this.webTestClient.post().uri("/images").body(BodyInserters.fromMultipartData(multipartData))
	.accept(MediaType.APPLICATION_JSON).exchange()
	.expectStatus().isOk().expectBody()
	.consumeWith(document("image-upload",
		requestPartFields("metadata", (1)
			fieldWithPath("version").description("The version of the image")))); (2)

1	配置 Spring REST 文档以生成一个代码段，用于描述名为的请求部分的有效负载中的字段。对使用 static 方法。`metadatarequestPartFieldsPayloadDocumentation`
2	期望一个路径为 . 对使用 static 方法。`versionfieldWithPathorg.springframework.restdocs.payload.PayloadDocumentation`

放心

Map<String, String> metadata = new HashMap<>();
metadata.put("version", "1.0");
RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("image-upload", requestPartFields("metadata", (1)
			fieldWithPath("version").description("The version of the image")))) (2)
	.when()
	.multiPart("image", new File("image.png"), "image/png")
	.multiPart("metadata", metadata)
	.post("images")
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST 文档以生成一个代码段，用于描述名为的请求部分的有效负载中的字段。对使用 static 方法。`metadatarequestPartFieldsPayloadDocumentation`
2	期望一个路径为 . 对使用 static 方法。`versionfieldWithPathorg.springframework.restdocs.payload.PayloadDocumentation`

结果是一个代码段，其中包含一个描述部件字段的表。此代码段名为。例如，记录名为的部件会生成一个名为的代码段。request-part-${part-name}-fields.adocmetadatarequest-part-metadata-fields.adocspring-doc.cn

在记录字段时，如果在部件的有效负载中找到未记录的字段，则测试将失败。同样，如果在部件的有效负载中找不到 documented 的字段，并且该字段尚未标记为可选，则测试也会失败。对于具有分层结构的有效负载，记录字段就足以使其所有后代也被视为已记录。spring-doc.cn

如果您不想记录字段，可以将其标记为已忽略。这样做可以防止它出现在生成的代码段中，同时避免上述失败。spring-doc.cn

您还可以在宽松模式下记录字段，其中任何未记录的字段都不会导致测试失败。为此，请使用上的方法。在记录您只想关注部件 payload 子集的特定场景时，这可能很有用。relaxedRequestPartFieldsorg.springframework.restdocs.payload.PayloadDocumentationspring-doc.cn

有关描述字段、记录使用 XML 的有效负载等的更多信息，请参阅记录请求和响应有效负载部分。spring-doc.cn

HTTP 标头

您可以分别使用和来记录请求或响应中的标头。以下示例说明如何执行此操作：requestHeadersresponseHeadersspring-doc.cn

MockMvc

this.mockMvc.perform(get("/people").header("Authorization", "Basic dXNlcjpzZWNyZXQ=")) (1)
	.andExpect(status().isOk())
	.andDo(document("headers", requestHeaders((2)
			headerWithName("Authorization").description("Basic auth credentials")), (3)
			responseHeaders((4)
					headerWithName("X-RateLimit-Limit")
						.description("The total number of requests permitted per period"),
					headerWithName("X-RateLimit-Remaining")
						.description("Remaining requests permitted in current period"),
					headerWithName("X-RateLimit-Reset")
						.description("Time at which the rate limit period will reset"))));

1	使用使用基本身份验证的标头执行请求。`GETAuthorization`
2	配置 Spring REST Docs 以生成描述请求标头的代码段。对使用 static 方法。`requestHeadersorg.springframework.restdocs.headers.HeaderDocumentation`
3	记录标题。对使用 static 方法。`AuthorizationheaderWithNameorg.springframework.restdocs.headers.HeaderDocumentation`
4	生成描述响应标头的代码段。对使用 static 方法。`responseHeadersorg.springframework.restdocs.headers.HeaderDocumentation`

WebTest客户端

this.webTestClient
	.get().uri("/people").header("Authorization", "Basic dXNlcjpzZWNyZXQ=") (1)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("headers",
		requestHeaders((2)
			headerWithName("Authorization").description("Basic auth credentials")), (3)
		responseHeaders((4)
			headerWithName("X-RateLimit-Limit")
				.description("The total number of requests permitted per period"),
			headerWithName("X-RateLimit-Remaining")
				.description("Remaining requests permitted in current period"),
			headerWithName("X-RateLimit-Reset")
				.description("Time at which the rate limit period will reset"))));

1	使用使用基本身份验证的标头执行请求。`GETAuthorization`
2	配置 Spring REST Docs 以生成描述请求标头的代码段。对使用 static 方法。`requestHeadersorg.springframework.restdocs.headers.HeaderDocumentation`
3	记录标题。对使用 static 方法。`AuthorizationheaderWithNameorg.springframework.restdocs.headers.HeaderDocumentation`
4	生成描述响应标头的代码段。对使用 static 方法。`responseHeadersorg.springframework.restdocs.headers.HeaderDocumentation`

放心

RestAssured.given(this.spec)
	.filter(document("headers", requestHeaders((1)
			headerWithName("Authorization").description("Basic auth credentials")), (2)
			responseHeaders((3)
					headerWithName("X-RateLimit-Limit")
						.description("The total number of requests permitted per period"),
					headerWithName("X-RateLimit-Remaining")
						.description("Remaining requests permitted in current period"),
					headerWithName("X-RateLimit-Reset")
						.description("Time at which the rate limit period will reset"))))
	.header("Authorization", "Basic dXNlcjpzZWNyZXQ=") (4)
	.when()
	.get("/people")
	.then()
	.assertThat()
	.statusCode(is(200));

1	配置 Spring REST Docs 以生成描述请求标头的代码段。对使用 static 方法。`requestHeadersorg.springframework.restdocs.headers.HeaderDocumentation`
2	记录标题。使用 'org.springframework.restdocs.headers.HeaderDocumentation' 上的 static 方法。`AuthorizationheaderWithName`
3	生成描述响应标头的代码段。对使用 static 方法。`responseHeadersorg.springframework.restdocs.headers.HeaderDocumentation`
4	使用使用基本身份验证的标头配置请求。`Authorization`

结果是一个名为的代码段和一个名为的代码段。每个 S 都包含一个描述 Headers 的表。request-headers.adocresponse-headers.adocspring-doc.cn

记录 HTTP 标头时，如果在请求或响应中找不到记录的标头，则测试将失败。spring-doc.cn

HTTP Cookie

您可以分别使用和在请求或响应中记录 Cookie。以下示例说明如何执行此操作：requestCookiesresponseCookiesspring-doc.cn

MockMvc

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"))));

1	使用 Cookie 发出 GET 请求。`JSESSIONID`
2	配置 Spring REST Docs 以生成描述请求的 cookie 的代码段。对使用 static 方法。`requestCookiesorg.springframework.restdocs.cookies.CookieDocumentation`
3	记录 Cookie。对使用 static 方法。`JSESSIONIDcookieWithNameorg.springframework.restdocs.cookies.CookieDocumentation`
4	生成描述响应的 Cookie 的代码段。对使用 static 方法。`responseCookiesorg.springframework.restdocs.cookies.CookieDocumentation`

WebTest客户端

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"))));

1	使用 Cookie 发出 GET 请求。`JSESSIONID`
2	配置 Spring REST Docs 以生成描述请求的 cookie 的代码段。对使用 static 方法。`requestCookiesorg.springframework.restdocs.cookies.CookieDocumentation`
3	记录 Cookie。对使用 static 方法。`JSESSIONIDcookieWithNameorg.springframework.restdocs.cookies.CookieDocumentation`
4	生成描述响应的 Cookie 的代码段。对使用 static 方法。`responseCookiesorg.springframework.restdocs.cookies.CookieDocumentation`

放心

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));

1	配置 Spring REST Docs 以生成描述请求的 cookie 的代码段。对使用 static 方法。`requestCookiesorg.springframework.restdocs.cookies.CookieDocumentation`
2	记录 Cookie。对使用 static 方法。`JSESSIONIDcookieWithNameorg.springframework.restdocs.cookies.CookieDocumentation`
3	生成描述响应的 Cookie 的代码段。对使用 static 方法。`responseCookiesorg.springframework.restdocs.cookies.CookieDocumentation`
4	随请求发送 Cookie。`JSESSIONID`

结果是一个名为的代码段和一个名为的代码段。每个 Cookie 都包含一个描述 Cookie 的表。request-cookies.adocresponse-cookies.adocspring-doc.cn

记录 HTTP Cookie 时，如果在请求或响应中找到未记录的 Cookie，则测试将失败。同样，如果未找到记录的 Cookie，并且该 Cookie 尚未标记为可选，则测试也会失败。您还可以在宽松模式下记录 Cookie，其中任何未记录的 Cookie 都不会导致测试失败。为此，请使用上的和方法。在记录您只想关注 Cookie 子集的特定方案时，这可能很有用。如果您不想记录 Cookie，可以将其标记为已忽略。这样做可以防止它出现在生成的代码段中，同时避免前面描述的故障。relaxedRequestCookiesrelaxedResponseCookiesorg.springframework.restdocs.cookies.CookieDocumentationspring-doc.cn

重用代码段

记录的 API 通常具有一些在其多个资源中通用的功能。为避免在记录此类资源时重复，您可以重复使用具有 common 元素的 Configured。Snippetspring-doc.cn

首先，创建描述 common elements 的。以下示例显示了如何执行此操作：Snippetspring-doc.cn

protected final LinksSnippet pagingLinks = links(
		linkWithRel("first").optional().description("The first page of results"),
		linkWithRel("last").optional().description("The last page of results"),
		linkWithRel("next").optional().description("The next page of results"),
		linkWithRel("prev").optional().description("The previous page of results"));

其次，使用此代码段并添加更多特定于资源的描述符。以下示例说明如何执行此操作：spring-doc.cn

MockMvc

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("example", this.pagingLinks.and((1)
			linkWithRel("alpha").description("Link to the alpha resource"),
			linkWithRel("bravo").description("Link to the bravo resource"))));

1	重用，调用以添加特定于正在记录的资源的描述符。`pagingLinksSnippetand`

WebTest客户端

this.webTestClient.get().uri("/").accept(MediaType.APPLICATION_JSON).exchange()
	.expectStatus().isOk().expectBody()
	.consumeWith(document("example", this.pagingLinks.and((1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))));

1	重用，调用以添加特定于正在记录的资源的描述符。`pagingLinksSnippetand`

放心

RestAssured.given(this.spec)
	.accept("application/json")
	.filter(document("example", this.pagingLinks.and((1)
			linkWithRel("alpha").description("Link to the alpha resource"),
			linkWithRel("bravo").description("Link to the bravo resource"))))
	.get("/")
	.then()
	.assertThat()
	.statusCode(is(200));

1	重用，调用以添加特定于正在记录的资源的描述符。`pagingLinksSnippetand`

该示例的结果是，具有、和值的链接都记录了出来。relfirstlastnextpreviousalphabravospring-doc.cn

记录约束

Spring REST Docs 提供了许多类，可以帮助您记录约束。您可以使用的实例来访问类的约束的描述。以下示例显示了如何执行此操作：ConstraintDescriptionsspring-doc.cn

public void example() {
	ConstraintDescriptions userConstraints = new ConstraintDescriptions(UserInput.class); (1)
	List<String> descriptions = userConstraints.descriptionsForProperty("name"); (2)
}

static class UserInput {

	@NotNull
	@Size(min = 1)
	String name;

	@NotNull
	@Size(min = 8)
	String password;

}

1	为类创建一个实例。`ConstraintDescriptionsUserInput`
2	获取属性约束的描述。此列表包含两个描述：一个用于约束，另一个用于约束。`nameNotNullSize`

Spring HATEOAS 示例中的 ApiDocumentation 类演示了此功能的实际应用。spring-doc.cn

查找约束

默认情况下，使用 Bean Validation 找到约束。目前仅支持属性约束。您可以通过使用自定义实例创建来自定义。要完全控制约束解析，您可以使用自己的 .ValidatorValidatorConstraintDescriptionsValidatorConstraintResolverConstraintResolverspring-doc.cn

描述约束

为所有 Bean Validation 3.0 的约束提供了默认描述：spring-doc.cn

AssertFalsespring-doc.cn
AssertTruespring-doc.cn
DecimalMaxspring-doc.cn
DecimalMinspring-doc.cn
Digitsspring-doc.cn
Emailspring-doc.cn
Futurespring-doc.cn
FutureOrPresentspring-doc.cn
Maxspring-doc.cn
Minspring-doc.cn
Negativespring-doc.cn
NegativeOrZerospring-doc.cn
NotBlankspring-doc.cn
NotEmptyspring-doc.cn
NotNullspring-doc.cn
Nullspring-doc.cn
Pastspring-doc.cn
PastOrPresentspring-doc.cn
Patternspring-doc.cn
Positivespring-doc.cn
PositiveOrZerospring-doc.cn
Sizespring-doc.cn

还为 Hibernate 中的以下约束提供了默认描述验证人：spring-doc.cn

CodePointLengthspring-doc.cn
CreditCardNumberspring-doc.cn
Currencyspring-doc.cn
EANspring-doc.cn
Emailspring-doc.cn
Lengthspring-doc.cn
LuhnCheckspring-doc.cn
Mod10Checkspring-doc.cn
Mod11Checkspring-doc.cn
NotBlankspring-doc.cn
NotEmptyspring-doc.cn
Currencyspring-doc.cn
Rangespring-doc.cn
SafeHtmlspring-doc.cn
URLspring-doc.cn

要覆盖默认描述或提供新描述，您可以创建基本名称为 . 基于 Spring HATEOAS 的示例包含此类资源包的示例。org.springframework.restdocs.constraints.ConstraintDescriptionsspring-doc.cn

资源包中的每个键都是约束的完全限定名称加上 . 例如，标准约束的键是。.description@NotNulljakarta.validation.constraints.NotNull.descriptionspring-doc.cn

您可以在描述中使用引用约束属性的属性占位符。例如，约束的默认描述是指约束的属性。@MinMust be at least ${value}valuespring-doc.cn

要更好地控制约束描述解析，可以使用自定义 . 要获得完全控制权，您可以使用自定义实施进行创建。ConstraintDescriptionsResourceBundleConstraintDescriptionResolverConstraintDescriptionsConstraintDescriptionResolverspring-doc.cn

在生成的代码段中使用约束描述

获得约束的描述后，您可以在生成的代码片段中随意使用它们。例如，您可能希望将约束描述作为字段描述的一部分。或者，您也可以将约束作为额外信息包含在请求字段代码段中。基于 Spring HATEOAS 的示例中的 ApiDocumentation 类说明了后一种方法。spring-doc.cn

默认代码段

当您记录请求和响应时，会自动生成许多代码段。spring-doc.cn

片段描述

curl-request.adocspring-doc.cn

包含等效于正在记录的调用的 curl 命令。MockMvcspring-doc.cn

httpie-request.adocspring-doc.cn

包含等效于正在记录的调用的 HTTPie 命令。MockMvcspring-doc.cn

http-request.adocspring-doc.cn

包含等效于正在记录的调用的 HTTP 请求。MockMvcspring-doc.cn

http-response.adocspring-doc.cn

包含返回的 HTTP 响应。spring-doc.cn

request-body.adocspring-doc.cn

包含已发送的请求的正文。spring-doc.cn

response-body.adocspring-doc.cn

包含返回的响应的正文。spring-doc.cn

您可以配置默认生成的代码段。有关更多信息，请参阅配置部分。spring-doc.cn

使用参数化输出目录

您可以参数化使用的输出目录。支持以下参数：documentspring-doc.cn

参数

描述

{方法名称}spring-doc.cn

测试方法的未修改名称。spring-doc.cn

{方法名称}spring-doc.cn

测试方法的名称，使用 kebab-case 格式化。spring-doc.cn

{method_name}spring-doc.cn

测试方法的名称，使用 snake_case 设置格式。spring-doc.cn

{类名}spring-doc.cn

测试类的未修改的简单名称。spring-doc.cn

{类名}spring-doc.cn

测试类的简单名称，使用 kebab-case 格式化。spring-doc.cn

{class_name}spring-doc.cn

测试类的简单名称，使用 snake_case 格式设置。spring-doc.cn

{步骤}spring-doc.cn

在当前测试中对服务进行的调用计数。spring-doc.cn

例如，在上命名的测试方法中，测试类将代码段写入名为 .document("{class-name}/{method-name}")creatingANoteGettingStartedDocumentationgetting-started-documentation/creating-a-notespring-doc.cn

参数化输出目录与方法结合使用时特别有用。它允许在 setup 方法中配置一次文档，然后在类中的每个测试中重用。以下示例说明如何执行此操作：@Beforespring-doc.cn

MockMvc

@Before
public void setUp() {
	this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
		.apply(documentationConfiguration(this.restDocumentation))
		.alwaysDo(document("{method-name}/{step}/"))
		.build();
}

放心

@Before
public void setUp() {
	this.spec = new RequestSpecBuilder().addFilter(documentationConfiguration(this.restDocumentation))
		.addFilter(document("{method-name}/{step}"))
		.build();
}

WebTest客户端

@Before
public void setUp() {
	this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
		.configureClient()
		.filter(documentationConfiguration(this.restDocumentation))
		.entityExchangeResultConsumer(document("{method-name}/{step}"))
		.build();
}

有了此配置，对您正在测试的服务的每次调用都会生成默认代码段，而无需任何进一步的配置。查看每个示例应用程序中的类，了解此功能的实际应用。GettingStartedDocumentationspring-doc.cn

自定义输出

本节介绍如何自定义 Spring REST Docs 的输出。spring-doc.cn

自定义生成的代码段

Spring REST Docs 使用 Mustache 模板来生成生成的代码片段。为 Spring REST Docs 可以生成的每个代码片段提供了默认模板。要自定义代码段的内容，您可以提供自己的模板。spring-doc.cn

模板是从 subpackage 的 Classpath 加载的。分包的名称由正在使用的模板格式的 ID 确定。默认模板格式 Asciidoctor 的 ID 为，因此代码片段是从加载的。每个模板都以其生成的代码段命名。例如，要覆盖代码段的模板，请创建一个名为 in 的模板。org.springframework.restdocs.templatesasciidoctororg.springframework.restdocs.templates.asciidoctorcurl-request.adoccurl-request.snippetsrc/test/resources/org/springframework/restdocs/templates/asciidoctorspring-doc.cn

包括额外信息

有两种方法可以提供额外的信息以包含在生成的代码段中：spring-doc.cn

对描述符使用 method 向其添加一个或多个属性。attributesspring-doc.cn
在调用、、、等时传入一些属性。此类属性与整个代码段相关联。curlRequesthttpRequesthttpResponsespring-doc.cn

在模板渲染过程中，任何其他属性都可用。与自定义代码段模板结合使用，这样就可以在生成的代码段中包含额外信息。spring-doc.cn

一个具体的例子是在记录请求字段时添加 constraints 列和 title。第一步是为您记录的每个字段提供一个属性，并提供一个属性。以下示例说明如何执行此操作：constraintstitlespring-doc.cn

MockMvc

.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)

1	配置请求字段代码段的属性。`title`
2	设置字段的属性。`constraintsname`
3	设置字段的属性。`constraintsemail`

WebTest客户端

.consumeWith(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)

1	配置请求字段代码段的属性。`title`
2	设置字段的属性。`constraintsname`
3	设置字段的属性。`constraintsemail`

放心

.filter(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)

1	配置请求字段代码段的属性。`title`
2	设置字段的属性。`constraintsname`
3	设置字段的属性。`constraintsemail`

第二步是提供一个名为的自定义模板，该模板包含有关生成的代码片段表中字段约束的信息，并添加标题。request-fields.snippetspring-doc.cn

.{{title}} (1)
|===
|Path|Type|Description|Constraints (2)

{{#fields}}
|{{path}}
|{{type}}
|{{description}}
|{{constraints}} (3)

{{/fields}}
|===

1	向表添加标题。
2	添加一个名为 “Constraints” 的新列。
3	在表的每一行中包含 descriptors' 属性。`constraints`