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

Documenting your API

This section provides more details about using Spring REST Docs to document your API.spring-doc.cn

Hypermedia

Spring REST Docs provides support for documenting the links in a hypermedia-based API. The following examples show how to use it: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	Configure Spring REST docs to produce a snippet describing the response’s links. Uses the static `links` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
2	Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
3	Expect a link whose `rel` is `bravo`.

WebTestClient

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	Configure Spring REST docs to produce a snippet describing the response’s links. Uses the static `links` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
2	Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
3	Expect a link whose `rel` is `bravo`.

REST Assured

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	Configure Spring REST docs to produce a snippet describing the response’s links. Uses the static `links` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
2	Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
3	Expect a link whose `rel` is `bravo`.

The result is a snippet named links.adoc that contains a table describing the resource’s links.spring-doc.cn

If a link in the response has a title, you can omit the description from its descriptor and the title is used. If you omit the description and the link does not have a title, a failure occurs.

When documenting links, the test fails if an undocumented link is found in the response. Similarly, the test also fails if a documented link is not found in the response and the link has not been marked as optional.spring-doc.cn

If you do not want to document a link, you can mark it as ignored. Doing so prevents it from appearing in the generated snippet while avoiding the failure described above.spring-doc.cn

You can also document links in a relaxed mode, where any undocumented links do not cause a test failure. To do so, use the relaxedLinks method on org.springframework.restdocs.hypermedia.HypermediaDocumentation. This can be useful when documenting a particular scenario where you only want to focus on a subset of the links.spring-doc.cn

Hypermedia Link Formats

Two link formats are understood by default:spring-doc.cn

Atom: Links are expected to be in an array named links. This is used by default when the content type of the response is compatible with application/json.spring-doc.cn
HAL: Links are expected to be in a map named _links. This is used by default when the content type of the response is compatible with application/hal+json.spring-doc.cn

If you use Atom- or HAL-format links but with a different content type, you can provide one of the built-in LinkExtractor implementations to links. The following examples show how to do so:spring-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	Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.

WebTestClient

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

1	Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.

REST Assured

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

1	Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.

If your API represents its links in a format other than Atom or HAL, you can provide your own implementation of the LinkExtractor interface to extract the links from the response.spring-doc.cn

Ignoring Common Links

Rather than documenting links that are common to every response, such as self and curies when using HAL, you may want to document them once in an overview section and then ignore them in the rest of your API’s documentation. To do so, you can build on the support for reusing snippets to add link descriptors to a snippet that is preconfigured to ignore certain links. The following example shows how to do so:spring-doc.cn

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

Request and Response Payloads

In addition to the hypermedia-specific support described earlier, support for general documentation of request and response payloads is also provided.spring-doc.cn

By default, Spring REST Docs automatically generates snippets for the body of the request and the body of the response. These snippets are named request-body.adoc and response-body.adoc respectively.spring-doc.cn

Request and Response Fields

To provide more detailed documentation of a request or response payload, support for documenting the payload’s fields is provided.spring-doc.cn

Consider the following payload:spring-doc.cn

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

You can document the previous example’s fields as follows: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	Configure Spring REST docs to produce a snippet describing the fields in the response payload. To document a request, you can use `requestFields`. Both are static methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
2	Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.name`.

WebTestClient

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	Configure Spring REST docs to produce a snippet describing the fields in the response payload. To document a request, you can use `requestFields`. Both are static methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
2	Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.name`.

REST Assured

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	Configure Spring REST docs to produce a snippet describing the fields in the response payload. To document a request, you can use `requestFields`. Both are static methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
2	Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.name`.

The result is a snippet that contains a table describing the fields. For requests, this snippet is named request-fields.adoc. For responses, this snippet is named response-fields.adoc.spring-doc.cn

When documenting fields, the test fails if an undocumented field is found in the payload. Similarly, the test also fails if a documented field is not found in the payload and the field has not been marked as optional.spring-doc.cn

If you do not want to provide detailed documentation for all of the fields, an entire subsection of a payload can be documented. The following examples show how to do so: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	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen as having also been documented. Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.

WebTestClient

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	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen as having also been documented. Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.

REST Assured

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	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen as having also been documented. Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.

subsectionWithPath can be useful for providing a high-level overview of a particular section of a payload. You can then produce separate, more detailed documentation for a subsection. See Documenting a Subsection of a Request or Response Payload.spring-doc.cn

If you do not want to document a field or subsection at all, you can mark it as ignored. This prevents it from appearing in the generated snippet while avoiding the failure described earlier.spring-doc.cn

You can also document fields in a relaxed mode, where any undocumented fields do not cause a test failure. To do so, use the relaxedRequestFields and relaxedResponseFields methods on org.springframework.restdocs.payload.PayloadDocumentation. This can be useful when documenting a particular scenario where you want to focus only on a subset of the payload.spring-doc.cn

By default, Spring REST Docs assumes that the payload you are documenting is JSON. If you want to document an XML payload, the content type of the request or response must be compatible with application/xml.

Fields in JSON Payloads

This section describes how to work with fields in JSON payloads.spring-doc.cn

JSON Field Paths

JSON field paths use either dot notation or bracket notation. Dot notation uses '.' to separate each key in the path (for example, a.b). Bracket notation wraps each key in square brackets and single quotation marks (for example, ['a']['b']). In either case, [] is used to identify an array. Dot notation is more concise, but using bracket notation enables the use of . within a key name (for example, ['a.b']). The two different notations can be used in the same path (for example, a['b']).spring-doc.cn

Consider the following JSON payload:spring-doc.cn

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

In the preceding JSON payload, the following paths are all present:spring-doc.cn

Path Value

Path	Value
`a`spring-doc.cn	An object containing `b`spring-doc.cn
`a.b`spring-doc.cn	An array containing three objectsspring-doc.cn
`['a']['b']`spring-doc.cn	An array containing three objectsspring-doc.cn
`a['b']`spring-doc.cn	An array containing three objectsspring-doc.cn
`['a'].b`spring-doc.cn	An array containing three objectsspring-doc.cn
`a.b[]`spring-doc.cn	An array containing three objectsspring-doc.cn
`a.b[].c`spring-doc.cn	An array containing the strings `one` and `two`spring-doc.cn
`a.b[].d`spring-doc.cn	The string `three`spring-doc.cn
`a['e.dot']`spring-doc.cn	The string `four`spring-doc.cn
`['a']['e.dot']`spring-doc.cn	The string `four`spring-doc.cn

aspring-doc.cn

An object containing bspring-doc.cn

a.bspring-doc.cn