JavaDocs与Spring Auto Rest Docs关联失败，生成文档文件为空求助

我来帮你搞定这个问题——你遇到的空文档问题，核心是没把RestDocs的测试驱动生成逻辑、Javadoc插件和Asciidoctor的整合给串起来，我一步步给你捋清楚：

1. 先补全必要的依赖和插件 #

你只配置了maven-javadoc-plugin还不够，Spring Auto Rest Docs需要结合测试插件和Asciidoctor插件才能把JavaDocs和API元数据整合起来：

第一步：添加测试依赖 #

在pom.xml的<dependencies>里加上RestDocs的MockMvc依赖：

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>2.0.6.RELEASE</version> <!-- 选和你的Spring Boot版本适配的版本 -->
    <scope>test</scope>
</dependency>

第二步：添加Asciidoctor插件 #

在<build>的<plugins>里加入这个插件，负责把snippets（测试生成的API片段）和JavaDocs整合为最终文档：

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.0</version>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>src/main/asciidoc</sourceDirectory>
                <backend>html</backend>
                <attributes>
                    <snippets>${project.build.directory}/generated-snippets</snippets>
                    <javadoc>${project.build.directory}/apidocs</javadoc>
                </attributes>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>2.0.6.RELEASE</version>
        </dependency>
    </dependencies>
</plugin>

2. 修正你的Maven Javadoc插件配置 #

把你现有的javadoc插件配置调整成这样，确保它和Asciidoctor插件同阶段执行，并且输出路径能被Asciidoctor识别：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <executions>
        <execution>
            <id>javadoc</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <destinationDirectory>${project.build.directory}/apidocs</destinationDirectory>
                <additionalparam>-Xdoclint:none</additionalparam> <!-- 避免文档检查报错中断构建 -->
            </configuration>
        </execution>
    </executions>
</plugin>

3. 写测试用例生成API Snippets（关键！） #

划重点：Spring Auto Rest Docs不是静态扫描代码生成文档，必须通过MockMvc测试来抓取API的请求/响应、参数等元数据，生成对应的snippets，否则adoc文件根本没内容可填充。

举个简单的测试示例：

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;

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.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "${project.build.directory}/generated-snippets")
public class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void getUserById() throws Exception {
        // 模拟请求你的API接口
        mockMvc.perform(get("/users/{id}", 1))
                .andExpect(status().isOk())
                // 这句会自动生成该API的请求、响应、参数等snippets文件
                .andDo(document("get-user-by-id"));
    }
}

4. 给你的auto-description.adoc加引用模板 #

空的adoc文件是因为你没告诉Asciidoctor要整合哪些内容，在src/main/asciidoc/auto-description.adoc里添加类似这样的内容：

= 我的API文档
:toc: left

== 用户管理API

=== 根据ID获取用户
// 引用测试生成的API请求/响应片段
include::{snippets}/get-user-by-id/http-request.adoc[]
include::{snippets}/get-user-by-id/http-response.adoc[]

// 引用JavaDocs内容
include::{javadoc}/com/example/demo/controller/UserController.html[]

5. 执行Maven命令生成完整文档 #

别用STS的普通JavaDocs生成按钮，执行这个Maven命令：

mvn clean prepare-package

这个命令会按顺序执行：清理→编译→运行测试生成snippets→生成JavaDocs→Asciidoctor整合所有内容生成最终的HTML文档。

最后去target/generated-docs目录看看，你会发现auto-description.adoc已经被填充了内容，还有生成好的完整API文档。

内容的提问来源于stack exchange，提问作者GoPro