Generate Spring Boot API Docs Instantly with Smart-Doc – A Complete Guide

Introduction

API documentation is a cornerstone of any project, defining interfaces, parameters and return values to improve development efficiency and reduce communication costs. Common documentation tools include Markdown, Word/WPS, Swagger/OpenAPI and MinDoc, each with its own strengths and limitations.

Why Smart-Doc?

Smart-Doc is a Java‑focused tool that automatically generates REST API, WebSocket, Apache Dubbo RPC and gRPC documentation by analyzing source code. It requires only standard Javadoc comments, avoiding any annotation overhead.

Core Features

Zero‑annotation, zero‑learning‑curve.

Automatic inference of return structures.

Supports Spring MVC, Spring Boot, Spring WebFlux, Feign, JAX‑RS.

Handles asynchronous return types such as Callable, Future, CompletableFuture.

Integrates JSR‑303 validation.

Generates request examples and JSON response examples.

Loads external source code (including sources JARs) for field comments.

Outputs multiple formats: Markdown, HTML5, Word, Asciidoctor, Postman Collection, OpenAPI 3.0.

Creates JMeter performance test scripts.

Exports error codes and data dictionaries.

Provides an interactive HTML5 page for file upload/download testing.

Supports Apache Dubbo RPC, gRPC and Java WebSocket.

Practical Example

1. Environment

Spring Boot 3.4.2

2. Maven Plugin Configuration

<plugin>
  <groupId>com.ly.smart-doc</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>[latest version]</version>
  <configuration>
    <!-- skip option to disable plugin in sub-modules -->
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <excludes>
      <exclude>com.google.guava:guava</exclude>
    </excludes>
    <includes>
      <include>com.alibaba:fastjson</include>
    </includes>
    <projectName>Comprehensive API Management</projectName>
  </configuration>
  <executions>
    <execution>
      <phase>compile</phase>
      <goals>
        <goal>html</goal>
      </goals>
    </execution>
  </executions>
</plugin>

3. smart-doc.json Configuration

{
  "outPath": "./src/main/resources/doc",
  "serverUrl": "http://localhost:8080"
}

4. Generating Documentation

Run the following Maven commands to produce different output formats:

mvn -Dfile.encoding=UTF-8 smart-doc:html      // HTML format
mvn -Dfile.encoding=UTF-8 smart-doc:markdown  // Markdown format
mvn -Dfile.encoding=UTF-8 smart-doc:adoc      // Asciidoctor format
mvn -Dfile.encoding=UTF-8 smart-doc:postman   // Postman collection
mvn -Dfile.encoding=UTF-8 smart-doc:openapi   // OpenAPI 3.0+
#mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest // Push to Torna platform
mvn -Dfile.encoding=UTF-8 smart-doc:word      // Word document
mvn -Dfile.encoding=UTF-8 smart-doc:jmeter    // JMeter script
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html   // Dubbo RPC HTML
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown // Dubbo RPC Markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc   // Dubbo RPC Asciidoctor

5. Excluding Packages

To prevent documentation generation for specific packages, add an exclusion filter in smart-doc.json:

{
  "outPath": "./src/main/resources/doc",
  "serverUrl": "http://localhost:8080",
  "packageExcludeFilters": "com.pack.test.controller"
}

6. Additional Configuration

For a full list of configuration options, refer to the official guide: https://smart-doc-group.github.io/guide/what-is-smart-doc

Visual Steps

Below are screenshots illustrating the plugin setup, JSON configuration, command execution and generated documentation views.