Spring REST Docs

https://github.com/spring-projects/spring-restdocs
Admin
Spring REST Docs is a tool that makes it easy to document RESTful services by combining hand-written...
Tokens:105,827
Snippets:694
Trust Score:9.7
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Invoke RESTful service with MockMvc, RestTestClient, and WebTestClient

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Shows how to invoke the root of the service and document the call. The MockMvc example includes callouts for invoking, asserting, and documenting. The RestTestClient example includes callouts for invoking, asserting, and documenting. The WebTestClient example includes callouts for invoking, asserting, and documenting.

```java
include-code::mockmvc/InvokeService[]
```

```java
include-code::resttestclient/InvokeService[]
```

```java
include-code::webtestclient/InvokeService[]
```

--------------------------------

### Configure MockMvc, RestTestClient, and WebTestClient tests without JUnit

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Shows how to call beforeTest and afterTest for each testing framework. The examples are shown in tabs for MockMvc, RestTestClient, and WebTestClient.

```java
include-code::mockmvc/ExampleApplicationTestNgTests[]
```

```java
include-code::resttestclient/ExampleApplicationTestNgTests[]
```

```java
include-code::webtestclient/ExampleApplicationTestNgTests[]
```

--------------------------------

### JSON array at root for field path example

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

Example JSON array used to illustrate documenting a payload with an array at its root. The path `[]` refers to the entire array.

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

--------------------------------

### GET /

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-asciidoctor/src/test/resources/operations/multiple-snippets.html

This snippet documents the GET request to the root endpoint of the service, as shown in the curl and HTTP request examples.

```APIDOC
## [GET] /

### Description
Retrieves the root resource of the service.

### Method
GET

### Endpoint
/

### Request Example
```
$ curl 'http://localhost:8080/' -i
```

### Response
#### Success Response (200)
No response body is documented.

```

--------------------------------

### JSON payload for wildcard field path example

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

Example JSON payload used to illustrate using `*` as a wildcard in field paths. The path `users.*.role` matches the role of every user.

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

--------------------------------

### JSON payload for field path examples

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

Example JSON payload used to illustrate JSON field paths. It contains nested objects, arrays, and a key with a dot in its name.

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

--------------------------------

### Example JSON payload

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

A sample JSON payload with a contact object containing name and email fields, used to illustrate field documentation.

```json
{
	"contact": {
		"name": "Jane Doe",
		"email": "jane.doe@example.com"
	}
}
```

--------------------------------

### HTTP request

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-asciidoctor/src/test/resources/operations/all-snippets.html

Shows the HTTP request line and headers for a GET request to the root path. Use this to understand the exact request format expected by the server.

```http
GET / HTTP/1.1
Host: localhost:8080
```

--------------------------------

### Curl request

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-asciidoctor/src/test/resources/operations/all-snippets.html

Shows a curl command to send a GET request to the root endpoint. Use this to test the service from the command line. The -i flag includes response headers in the output.

```bash
$ curl 'http://localhost:8080/' -i
```

--------------------------------

### JSON payload of a book for reusing field descriptors

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

Example JSON payload of a book used to illustrate reusing field descriptors. The paths for `title` and `author` are `title` and `author`.

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

--------------------------------

### Format table columns with cols attribute

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Customize table column widths by using the cols attribute before including a snippet. The example sets the width split across two columns, with the second column three times as wide as the first.

```asciidoc
[cols="1,3"] // <1>
\include::{snippets}/index/links.adoc[]
```

--------------------------------

### Override output directory for RestDocumentationExtension

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Override the default output directory for RestDocumentationExtension by registering it as a field with a custom directory name. The example uses "custom" as the output directory.

```java
public class JUnit6ExampleTests {

	@RegisterExtension
	final RestDocumentationExtension restDocumentation = new RestDocumentationExtension ("custom");

}
```

--------------------------------

### Apply RestDocumentationExtension and SpringExtension to JUnit 6 test class

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Apply both RestDocumentationExtension and SpringExtension to a JUnit 6 test class when testing a typical Spring application. This setup is used before configuring MockMvc or WebTestClient with the documentation configurer.

```java
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class JUnit6ExampleTests {
```

--------------------------------

### Build the samples with Gradle

Source: https://github.com/spring-projects/spring-restdocs/blob/main/CONTRIBUTING.md

Run this command to build the sample projects included in the repository.

```bash
$ ./gradlew buildSamples
```

--------------------------------

### Build the project with Gradle

Source: https://github.com/spring-projects/spring-restdocs/blob/main/CONTRIBUTING.md

Run this command from the project root to build the source code. Requires Java 17 or later.

```bash
$ ./gradlew build
```

--------------------------------

### Include generated documentation in jar (Maven and Gradle)

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Configure the build to include generated Asciidoctor documentation in the application jar. The Maven configuration declares the Asciidoctor plugin (callout <1>) and a maven-resources-plugin execution that copies generated docs from the build directory to the build output's static/docs directory (callout <3>), ensuring the jar includes them. The Gradle configuration modifies the bootJar task to depend on the asciidoctor task (callout <1>) and copies its output into the jar's static/docs directory (callout <2>).

```xml
	<plugin> <1>
		<groupId>org.asciidoctor</groupId>
		<artifactId>asciidoctor-maven-plugin</artifactId>
		<!-- … -->
	</plugin>
	<plugin> <2>
		<artifactId>maven-resources-plugin</artifactId>
		<executions>
			<execution>
				<id>copy-resources</id>
				<phase>prepare-package</phase>
				<goals>
					<goal>copy-resources</goal>
				</goals>
				<configuration> <3>
					<outputDirectory>
						${project.build.outputDirectory}/static/docs
					</outputDirectory>
					<resources>
						<resource>
							<directory>
								${project.build.directory}/generated-docs
							</directory>
						</resource>
					</resources>
				</configuration>
			</execution>
		</executions>
	</plugin>
```

```groovy
	bootJar {
		dependsOn asciidoctor <1>
		from ("${asciidoctor.outputDir}") { <2>
			into 'static/docs'
		}
	}
```

--------------------------------

### Build Spring REST Docs with Gradle

Source: https://github.com/spring-projects/spring-restdocs/blob/main/README.md

Use this command to build the project from source. Requires Java 17 or later and Gradle. The build is executed with the command './gradlew build'.

```shell
./gradlew build
```

--------------------------------

### Generate Eclipse project metadata

Source: https://github.com/spring-projects/spring-restdocs/blob/main/CONTRIBUTING.md

Run this command to generate Eclipse project and classpath files. After running it, import the project into Eclipse using File -> Import... -> General -> Existing Projects into Workspace.

```bash
$ ./gradlew eclipse
```

--------------------------------

### Manual equivalent of operation macro with snippets

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Equivalent manual inclusion of the curl-request, http-request, and http-response snippets using the include macro. Each snippet is wrapped in a section with a title and an anchor.

```asciidoc
[[example_curl_request]]
= Curl request

\include::{snippets}/index/curl-request.adoc[]

[[example_http_request]]
= HTTP request

\include::{snippets}/index/http-request.adoc[]

[[example_http_response]]
= HTTP response

\include::{snippets}/index/http-response.adoc[]
```

--------------------------------

### Maven build configuration for Spring REST Docs with MockMvc

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Maven build configuration for Spring REST Docs with MockMvc. Adds the spring-restdocs-mockmvc test dependency and the Asciidoctor Maven plugin (version 3.2.0) that runs process-asciidoc during prepare-package. The spring-restdocs-asciidoctor dependency automatically configures the snippets attribute to target/generated-snippets and enables the operation block macro; requires AsciidoctorJ 3.0. Use spring-restdocs-webtestclient instead if you use WebTestClient.

```xml
	<dependency> <1>
		<groupId>org.springframework.restdocs</groupId>
		<artifactId>spring-restdocs-mockmvc</artifactId>
		<version>{project-version}</version>
		<scope>test</scope>
	</dependency>

	<build>
		<plugins>
			<plugin> <2>
				<groupId>org.asciidoctor</groupId>
				<artifactId>asciidoctor-maven-plugin</artifactId>
				<version>3.2.0</version>
				<executions>
					<execution>
						<id>generate-docs</id>
						<phase>prepare-package</phase> // <3>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>html</backend>
							<doctype>book</doctype>
						</configuration>
					</execution>
				</executions>
				<dependencies>
					<dependency> <4>
						<groupId>org.springframework.restdocs</groupId>
						<artifactId>spring-restdocs-asciidoctor</artifactId>
						<version>{project-version}</version>
					</dependency>
				</dependencies>
			</plugin>
		</plugins>
	</build>
```

--------------------------------

### Gradle build configuration for Spring REST Docs with MockMvc

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Gradle build configuration for Spring REST Docs with MockMvc. Applies the Asciidoctor plugin (version 4.0.5) and sets AsciidoctorJ to 3.0.0. Declares the asciidoctorExt configuration for the spring-restdocs-asciidoctor dependency, which configures the snippets attribute to build/generated-snippets and enables the operation block macro. The test task writes to snippetsDir and the asciidoctor task reads from it, depends on test, and uses the asciidoctorExt configuration; both input/output declarations are required for incremental builds.

```groovy
	plugins { <1>
		id "org.asciidoctor.jvm.convert" version "4.0.5"
	}

	asciidoctorj { <2>
		version = "3.0.0"
	}

	configurations {
		asciidoctorExt <3>
	}

	dependencies {
		asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <4>
		testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' <5>
	}

	ext { <6>
		snippetsDir = file('build/generated-snippets')
	}

	tasks.named("test") { <7>
		outputs.dir snippetsDir
	}

	tasks.named("asciidoctor") { <8>
		inputs.dir snippetsDir <9>
		configurations 'asciidoctorExt' <10>
		dependsOn test <11>
	}
```

--------------------------------

### JSON array of books

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

JSON array of book objects with title and author fields. The paths for title and author are [].title and [].author, respectively.

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

```

--------------------------------

### Custom snippet

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-asciidoctor/src/test/resources/operations/all-snippets.html

Displays a custom snippet with the content 'mycustomsnippet-äöü'. This is a placeholder for user-defined snippets in the documentation.

```text
mycustomsnippet-äöü
```

--------------------------------

### Include all snippets with operation macro

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Use the operation macro to include all generated snippets for an operation. The macro target is the operation name, and it is available after adding spring-restdocs-asciidoctor to the build configuration.

```asciidoc
operation::index[]
```

--------------------------------

### Set table title with dot prefix

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Sets the table title to 'Links' by prefixing a line with a dot. The include directive pulls in the snippet content.

```asciidoc
.Links // <1>
\include::{snippets}/index/links.adoc[]
```

--------------------------------

### Select snippets with operation macro snippets attribute

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Use the operation macro with the snippets attribute to select specific snippet files. The attribute value is a comma-separated list of snippet file names without the .adoc suffix.

```asciidoc
operation::index[snippets='curl-request,http-request,http-response']
```

--------------------------------

### Response fields table

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-asciidoctor/src/test/resources/operations/all-snippets.html

Presents a table of response fields with their types and descriptions. The fields are 'a' (Object), 'a.b' (Number), and 'a.c' (String). Use this to document the structure of the JSON response.

```markdown
| Path | Type | Description |
| --- | --- | --- |
| `a` | `Object` | one |
| `a.b` | `Number` | two |
| `a.c` | `String` | three |
```

--------------------------------

### Include individual snippet with include macro

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Include an individual snippet using the include macro. The snippets attribute is automatically set by spring-restdocs-asciidoctor and references the snippets output directory.

```asciidoc
\include::{snippets}/index/curl-request.adoc[]
```

--------------------------------

### JSON response body with nested weather

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

JSON response body with nested weather, wind, and temperature objects. Used to demonstrate documenting a subsection of a payload.

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

```

--------------------------------

### Custom template for request-fields.snippet

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/how-to/pages/customizing-the-output.adoc

A Mustache template that adds a title and a 'Constraints' column to the request fields snippet table. It uses the `title` and `constraints` attributes provided by the descriptors. The template is named `request-fields.snippet` and placed in `src/test/resources/org/springframework/restdocs/templates/asciidoctor`.

```mustache
	.{{title}} // <1>
	|===
	|Path|Type|Description|Constraints // <2>

	{{#fields}}
	|{{path}}
	|{{type}}
	|{{description}}
	|{{constraints}} // <3>

	{{/fields}}
	|===

```

--------------------------------

### Response Fields

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-asciidoctor/src/test/resources/some-operation/response-fields.adoc

Describes the structure of the response fields for the some-operation operation.

```APIDOC
## Response Fields

### Description
This section documents the fields present in the response of the some-operation operation.

### Fields

| Path | Type | Description |
|------|------|-------------|
| `a` | `Object` | one |
| `a.b` | `Number` | two |
| `a.c` | `String` | three |
```

--------------------------------

### JSON subsection snippet for temperature

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/request-response-payloads.adoc

JSON snippet containing the temperature subsection of the response body. The snippet is named response-body-beneath-weather.temperature.adoc by default.

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

```

--------------------------------

### Customize snippet title with document attribute

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Customize the default title for a built-in snippet by setting a document attribute. The attribute name follows the pattern operation-{snippet}-title, e.g., operation-curl-request-title.

```asciidoc
:operation-curl-request-title: Example request
```

--------------------------------

### CookieDocumentation Methods

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/http-cookies.adoc

These methods are part of the CookieDocumentation class in Spring REST Docs. They allow you to document cookies in HTTP requests and responses, either strictly or in relaxed mode.

```APIDOC
## CookieDocumentation.requestCookies

### Description
Configures Spring REST Docs to produce a snippet describing the request's cookies. Use this method to document cookies in an HTTP request.

### Method
N/A (Static method on CookieDocumentation)

### Endpoint
N/A

### Parameters
- **request** (Request) - Required - The request whose cookies are to be documented.

### Request Example
N/A

### Response
#### Success Response
- **Snippet** (Snippet) - The generated snippet describing the request's cookies.

#### Response Example
N/A
```

```APIDOC
## CookieDocumentation.responseCookies

### Description
Configures Spring REST Docs to produce a snippet describing the response's cookies. Use this method to document cookies in an HTTP response.

### Method
N/A (Static method on CookieDocumentation)

### Endpoint
N/A

### Parameters
- **response** (Response) - Required - The response whose cookies are to be documented.

### Request Example
N/A

### Response
#### Success Response
- **Snippet** (Snippet) - The generated snippet describing the response's cookies.

#### Response Example
N/A
```

```APIDOC
## CookieDocumentation.cookieWithName

### Description
Creates a cookie descriptor for a cookie with the given name. Use this method to document a specific cookie in a request or response.

### Method
N/A (Static method on CookieDocumentation)

### Endpoint
N/A

### Parameters
- **name** (String) - Required - The name of the cookie to document.

### Request Example
N/A

### Response
#### Success Response
- **CookieDescriptor** (CookieDescriptor) - A descriptor for the cookie.

#### Response Example
N/A
```

```APIDOC
## CookieDocumentation.relaxedRequestCookies

### Description
Configures Spring REST Docs to produce a snippet describing the request's cookies in relaxed mode. In relaxed mode, undocumented cookies do not cause a test failure.

### Method
N/A (Static method on CookieDocumentation)

### Endpoint
N/A

### Parameters
- **request** (Request) - Required - The request whose cookies are to be documented.

### Request Example
N/A

### Response
#### Success Response
- **Snippet** (Snippet) - The generated snippet describing the request's cookies.

#### Response Example
N/A
```

```APIDOC
## CookieDocumentation.relaxedResponseCookies

### Description
Configures Spring REST Docs to produce a snippet describing the response's cookies in relaxed mode. In relaxed mode, undocumented cookies do not cause a test failure.

### Method
N/A (Static method on CookieDocumentation)

### Endpoint
N/A

### Parameters
- **response** (Response) - Required - The response whose cookies are to be documented.

### Request Example
N/A

### Response
#### Success Response
- **Snippet** (Snippet) - The generated snippet describing the response's cookies.

#### Response Example
N/A
```

--------------------------------

### Apply RestDocumentationExtension to JUnit 6 test class

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Apply the RestDocumentationExtension to a JUnit 6 test class to enable Spring REST Docs snippet generation. The extension is automatically configured with an output directory based on the build tool: Maven uses target/generated-snippets, Gradle uses build/generated-snippets.

```java
@ExtendWith(RestDocumentationExtension.class)
public class JUnit6ExampleTests {
```

--------------------------------

### Define ManualRestDocumentation field

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/getting-started/index.adoc

Declares a private field of type ManualRestDocumentation, required when not using JUnit. This field is used to manage the lifecycle of the documentation.

```java
private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
```

--------------------------------

### Escape pipe characters with tableCellContent lambda

Source: https://github.com/spring-projects/spring-restdocs/blob/main/spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-asciidoctor.adoc

Escapes pipe characters in a table cell using the Mustache lambda 'tableCellContent'. Useful in custom templates to avoid table formatting problems.

```asciidoc
| {{#tableCellContent}}{{description}}{{/tableCellContent}}
```
Tokens:
Raw