I want to show you, what changes to your Maven pom.xml you have to make to add Spring Auto REST Docs to your project. At then end you only have to copy-and-paste some code from this blog and there you go!

Add Auto REST Docs

The first step is to add the dependencies for Spring REST Docs and Spring Auto REST Docs to your pom:

<dependencies>

    <!-- REST Docs -->
    <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>capital.scalable</groupId>
        <artifactId>spring-auto-restdocs-core</artifactId>
        <version>1.0.6</version>
        <scope>test</scope>
    </dependency>

</dependencies>

Changes to the build process

Property

Use a property to describe the output of the generates snippets:

<properties>

    <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>

</properties>

Surefire

The Maven test plugin Surefire has to be adopted to extract the JavaDoc into some JSON files for Spring Auto REST Docs:

<build>
    <plugins>

        <!-- Surefire -->
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <includes>
                    <include>**/*Test.java</include>
                </includes>
                <systemPropertyVariables>
                    <org.springframework.restdocs.outputDir>
                        ${snippetsDirectory}
                    </org.springframework.restdocs.outputDir>
                    <org.springframework.restdocs.javadocJsonDir>
                        ${project.build.directory}/generated-javadoc-json
                    </org.springframework.restdocs.javadocJsonDir>
                </systemPropertyVariables>
            </configuration>
        </plugin>

    </plugins>
</build>

Maybe you named the REST Docs test classes in a special way (e.g. with RDTest as the suffix) or put them all in a special directory. In this case adopt the <include> direction accordingly.

JavaDoc

For producing the right Asciidoctor format from the JavaDoc comments in your code you have to define a special Doclet:

<!-- Javadoc -->
<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <extensions>true</extensions>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>javadoc-no-fork</goal>
            </goals>
        </execution>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet
        </doclet>
        <docletArtifact>
            <groupId>capital.scalable</groupId>
            <artifactId>spring-auto-restdocs-json-doclet</artifactId>
            <version>1.0.6</version>
        </docletArtifact>
        <destDir>generated-javadoc-json</destDir>
        <reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
        <useStandardDocletOptions>false</useStandardDocletOptions>
        <show>package</show>
    </configuration>
</plugin>

Asciidoctor

The Asciidoctor plugin should produce either HTML or PDF. The necessary configuration looks like this:

<!-- Asciidoctor -->
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.11</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <doctype>book</doctype>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                </attributes>
            </configuration>
        </execution>
        <execution>
            <id>output-pdf</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <doctype>book</doctype>
                <attributes>
                    <icons>font</icons>
                    <pagenums/>
                    <toc/>
                    <idprefix/>
                    <idseparator>-</idseparator>
                </attributes>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <headerFooter>true</headerFooter>
        <attributes>
            <snippets>${snippetsDirectory}</snippets>
        </attributes>
    </configuration>
</plugin>

Asciidoctor expects the main document in the directory src/main/asciidoc. The output file has the same name as the main document.

As you can see in this example it is possible to configure the 2 output formats with different attributes. E.g. it makes sense to add page numbers only to PDF.

The right goal

When you want to produce the documentation you have to call Maven with this parameter:

verify asciidoctor:process-asciidoc@output-html

In the first step Maven executes the tests and produces the Asciidoctor snippets. Then it processes the main adoc and produces the HTML output. If you want to get the PDF use

verify asciidoctor:process-asciidoc@output-pdf

instead. In case the snippets were already created you can pass the verify.