Spring RestDocs无法生成前端页面求助：已生成snippets但无HTML

Hey there! Let's break down why your RestDocs setup isn't generating the HTML docs you're expecting—you've got the snippets part working, but you're missing the key pieces to turn those raw snippets into usable web pages and make them accessible via your Spring app. Here's how to fix it step by step:

1. 完善Maven插件配置 #

RestDocs only generates raw snippet files by default; you need the Asciidoctor Maven Plugin to convert those snippets into HTML, plus the Maven Resources Plugin to copy the generated HTML into Spring's static resource directory so it can be served to users.

Update your pom.xml plugins section with these additions:

<!-- 将snippets转换为HTML文档 -->
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.6</version> <!-- 使用最新稳定版本 -->
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>src/main/asciidoc</sourceDirectory>
                <outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
                <backend>html</backend>
                <attributes>
                    <!-- 指定snippets生成路径，需与RestDocs测试配置一致 -->
                    <snippets>${project.build.directory}/generated-snippets</snippets>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

<!-- 将生成的HTML复制到Spring静态资源目录 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <version>3.3.1</version>
    <executions>
        <execution>
            <id>copy-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
                <resources>
                    <resource>
                        <directory>${project.build.directory}/generated-docs</directory>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

2. 创建主Asciidoc文档 #

You need a main .adoc file that pulls in all your generated snippets. Create a directory src/main/asciidoc if it doesn't exist, then add an index.adoc file with content like this (adjust snippet paths to match your actual API endpoints):

= 我的REST API文档
:toc: left
:toclevels: 3
:icons: font

== 用户管理接口
include::{snippets}/user/get-user/adoc[]
include::{snippets}/user/create-user/adoc[]

== 订单管理接口
include::{snippets}/order/list-orders/adoc[]

Each include line references a snippet directory generated by your RestDocs test cases—make sure the paths match what's in your target/generated-snippets folder after running tests.

3. 确保RestDocs测试配置正确 #

In your test classes, double-check that snippets are being generated to the directory specified in the Asciidoctor plugin. Use the @AutoConfigureRestDocs annotation to set this explicitly:

@SpringBootTest
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class UserApiTests {
    // 你的测试用例逻辑...
}

4. 配置Spring MVC简化访问（可选） #

By default, the HTML will be accessible at http://localhost:8080/docs/index.html (adjust the port to match your app's config). If you want to use http://localhost/docs directly, add a Spring MVC config to redirect to the index file:

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/docs")
                .setViewName("forward:/docs/index.html");
    }
}

5. 生成并访问文档 #

Run these steps in order:

• Execute your test cases to generate snippets: mvn test
• Build the project to generate HTML and copy it to the static directory: mvn prepare-package
• Start your Spring Boot app
• Visit http://localhost:8080/docs (or http://localhost:8080/docs/index.html if you skipped the MVC config)

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