Spring REST Docs
It helps you to produce documentation that is accurate, concise, and well-structured. This documentation then allows your users to get the information they need with a minimum of fuss.
All edits by Oksana Shumei
{fileName}
authorization
Snippet name hard-coded inside Snippet class.
{header}
Authorization
Snippet header hard-coded inside Snippet class.
{link}
items-id
Derived from the documentation string. For example: items/id.
{sections}
<iterable>
Contains all sections (Snippet classes) which are configured to be included in the section snippet. Moustache templater iterates over this and expands into separate header and link lines.
{snippets}
target/generated-snippets
Base snippet folder configured via org.springframework.restdocs.outputDir system property.
Template placeholders
[[resources-{{link}}]]
=== {{title}}
include::auto-method-path.adoc[]
include::auto-description.adoc[]
{{#sections}}
==== {{header}}
{{#filenames}}
include::{{.}}.adoc[]
{{/filenames}}
{{/sections}}Template itself
include::{snippets}/your-endpoint/auto-section.adoc[]Asciidoc
The section snippet combines most common snippets into one convenient file. It helps you being even more lazy, because a single line of AsciiDoc is sufficient to document one endpoint. Assuming of course that you already documented your code with Javadoc.
Configuration
Configuration
failOnUndocumentedFields - if build should fail on at least one undocumented field
- failOnUndocumentedFields - if build should fail on at least one undocumented field
- responseBodyAsType - specified class should be considered as response type instead of endpoint method’s return type
responseBodyAsType - specified class should be considered as response type instead of endpoint method’s return type
Configuration
Configuration available during MockMvc setup:
failOnUndocumentedFields - if build should fail on at least one undocumented field
responseBodyAsType - specified class should be considered as response type instead of endpoint method’s return type
id
Integer
false
Unique item ID.
orderNumber
Integer
true
Item’s order number.
Must be at least 1.
Result
@GetMapping("{id}")
public ItemResponse getItem(@PathVariable String id) { ... }
static class ItemResponse {
/**
* Unique item ID.
*/
@NotBlank
private String id;
/**
* Item's order number.
*/
@Min(1)
private Integer orderNumber;
}Code
Response fields snippetResponse fields snippet automatically lists all fields of the response class, determined from return value of Controller’s method. List includes name, type, whether the field is optional, and its Javadoc with constraints.
Response fields snippet
Response fields snippet
Response fields snippet automatically lists all fields of the response class, determined from return value of Controller’s method. List includes name, type, whether the field is optional, and its Javadoc with constraints.
Response fields snippet
Configuration
Configuration
failOnUndocumentedFields - if build should fail on at least one undocumented field
- failOnUndocumentedFields - if build should fail on at least one undocumented field
- requestBodyAsType - specified class should be considered as request type instead of endpoint method’s parameter
requestBodyAsType - specified class should be considered as request type instead of endpoint method’s parameter
Configuration
Configuration available during MockMvc setup:
failOnUndocumentedFields - if build should fail on at least one undocumented field
requestBodyAsType - specified class should be considered as request type instead of endpoint method’s parameter
description
String
true
Item description.
Size must be between 0 and 20 inclusive.
id
Integer
false
Item ID.
Result
