Generate Spring REST Docs API Documentation in Minutes with Gradle or Maven

Overview

Guide to generate API documentation for a Spring Boot application using Spring REST Docs. Shows project setup with Gradle or Maven, a simple controller, building an executable JAR, writing tests that produce documentation snippets, and assembling Asciidoctor documentation.

Prerequisites

JDK 1.8+

Gradle 2.3+ or Maven 3.0+

Preferred IDE (STS, IntelliJ IDEA)

About 15 minutes

Project structure

Create the following package layout:

src/main/java/hello/
    HomeController.java
    Application.java
src/test/java/hello/
    WebLayerTest.java
src/main/asciidoc/
    index.adoc

Gradle build

buildscript {
    repositories { mavenCentral() }
    dependencies { classpath "org.springframework.boot:spring-boot-gradle-plugin:1.4.0.RELEASE" }
}
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'

jar {
    baseName = 'gs-testing-web'
    version = '0.1.0'
}

repositories { mavenCentral() }

sourceCompatibility = 1.8

dependencies {
    compile "org.springframework.boot:spring-boot-starter-web"
    testCompile "org.springframework.boot:spring-boot-starter-test"
    testCompile "org.springframework.restdocs:spring-restdocs-mockmvc"
}

Maven build

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.2.RELEASE</version>
    </parent>
    <groupId>org.springframework</groupId>
    <artifactId>gs-testing-restdocs</artifactId>
    <version>0.1.0</version>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

Source code

Controller returning a JSON greeting:

package hello;

import java.util.Collections;
import java.util.Map;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HomeController {
    @GetMapping("/")
    public Map<String, Object> greeting() {
        return Collections.singletonMap("message", "Hello World");
    }
}

Main application class:

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Running the application

Gradle: ./gradlew bootRun or ./gradlew build then java -jar build/libs/gs-testing-web-0.1.0.jar Maven: ./mvnw spring-boot:run or ./mvnw clean package then

java -jar target/gs-testing-restdocs-0.1.0.jar

Test that generates documentation

Web‑layer test using MockMvc and Spring REST Docs:

package hello;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@RunWith(SpringRunner.class)
@WebMvcTest(HomeController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/"))
            .andDo(print())
            .andExpect(status().isOk())
            .andExpect(content().string(containsString("Hello World")))
            .andDo(document("home"));
    }
}

Running the test creates target/snippets/home with Asciidoctor snippets such as http-request.adoc and http-response.adoc.

Assembling the documentation

Create src/main/asciidoc/index.adoc and include the generated snippets:

= Spring REST Docs Example

include::{snippets}/home/http-request.adoc[]
include::{snippets}/home/http-response.adoc[]

Configure the Asciidoctor plugin to set the snippets attribute to the snippet directory. Example Maven configuration:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDocumentName>index.adoc</sourceDocumentName>
                <backend>html</backend>
                <attributes>
                    <snippets>${project.build.directory}/snippets</snippets>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

For Gradle, apply the org.asciidoctor.convert plugin and configure the asciidoctor task with the same attributes.

Result

After building, the generated HTML (or other format) contains up‑to‑date request/response examples and optional curl/httpie commands. Because the documentation is produced from the test suite, any API change that breaks the test also breaks documentation generation, ensuring consistency.

Summary

The steps above produce a runnable Spring Boot JAR and automatically generated API documentation using Spring REST Docs. The documentation can be packaged with the application or published as a static site.