Golden Recursion Inc. logoGolden Recursion Inc. logo
Advanced Search
Spring REST Docs

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 

Edits on 9 Feb, 2022
Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+6 rows) (+18 cells) (+18 characters)
Article

Placeholder
Example
Description

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

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+21 characters)
Article

Template placeholders

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+215 characters)
Article
[[resources-{{link}}]]
=== {{title}}

include::auto-method-path.adoc[]

include::auto-description.adoc[]
{{#sections}}

==== {{header}}

{{#filenames}}
include::{{.}}.adoc[]
{{/filenames}}
{{/sections}}
Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+15 characters)
Article

Template itself

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+53 characters)
Article
include::{snippets}/your-endpoint/auto-section.adoc[]
Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+8 characters)
Article

Asciidoc

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+255 characters)
Article

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.

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+210/-210 characters)
Article

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

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+255 characters)
Article

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

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+2 rows) (+8 cells) (+8 characters)
Article

Path
Type
Optional
Description

id

Integer

false

Unique item ID.

orderNumber

Integer

true

Item’s order number.

Must be at least 1.

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+6 characters)
Article

Result

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+292 characters)
Article
@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;
}
Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+4 characters)
Article

Code

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+23/-23 characters)
Article

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.

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+244/-23 characters)
Article

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.

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+23 characters)
Article

Response fields snippet

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+206/-206 characters)
Article

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

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+251 characters)
Article

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

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+2 rows) (+8 cells) (+8 characters)
Article

Path
Type
Optional
Description

description

String

true

Item description.

Size must be between 0 and 20 inclusive.

id

Integer

false

Item ID.

Oksana Shumei
Oksana Shumei edited on 9 Feb, 2022
Edits made to:
Article (+6 characters)
Article

Result

Golden logo
By using this site, you agree to our Terms & Conditions.