Asciidoctor Integration | Spring Rest Docs

Introduction

Asciidoctor is a popular text processor for converting AsciiDoc content into various formats such as HTML, PDF, and EPUB. In the context of Spring REST Docs, integrating Asciidoctor allows you to generate API documentation that is both readable and maintainable. This tutorial will guide you through the process of integrating Asciidoctor with a Spring application, ensuring that your API documentation is generated automatically alongside your tests.

Prerequisites

Before we start, ensure you have the following:

Java Development Kit (JDK) installed on your machine.
A working Spring Boot application.
Maven or Gradle as a build tool.

Setting Up Asciidoctor

To integrate Asciidoctor into your Spring project, you need to add the necessary dependencies. Depending on your build tool, the configuration will differ.

For Maven

Add the following dependencies to your pom.xml file:

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-spring-boot-starter</artifactId>
    <version>2.4.3</version>
</dependency>

For Gradle

Add the following dependencies to your build.gradle file:

implementation 'org.asciidoctor:asciidoctor-spring-boot-starter:2.4.3'

Configuring Spring REST Docs

To generate the documentation, you'll need to configure Spring REST Docs. In your application, add the following configuration to enable REST Docs:

@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class MyApiTests {
    // Your test cases here
}

Writing AsciiDoc Documentation

Create a new file named api-docs.adoc in your resources directory. This file will contain the AsciiDoc content for your API documentation. Here’s a simple example of how to document an endpoint:

= API Documentation

== User API

=== Create User

[role="get"]
=== Request

==== Request Body

[cols="1,1", options="header"]
|===
| Field | Description
| name  | The name of the user
| email | The email address of the user
|===

Generating Documentation

After writing your AsciiDoc documentation, you can generate the final documentation by executing the following command:

mvn clean package

This will compile your AsciiDoc files and create the HTML documentation in the target/generated-docs directory.

Viewing the Documentation

Once the build process is complete, navigate to the target/generated-docs folder and open the index.html file in your web browser to view the generated documentation.

Conclusion

Integrating Asciidoctor with Spring REST Docs provides a powerful way to create and maintain API documentation. By following this tutorial, you have learned how to set up Asciidoctor, configure Spring REST Docs, and generate HTML documentation from your AsciiDoc files. Now you can ensure that your API documentation remains updated and easily accessible.

Asciidoctor Integration Tutorial