为什么片段包含 spring-restdocs-asciidoctor 的错误？

Question

当我使用 spring-restdocs 和 asciidoctor 时，我确实可以生成 index.html，但它不能像这样生成请求或响应。​​

== /hello: Say "Hello World!"

operation::hello[]

.request
include::{snippets}/hello/http-request.adoc[]

.response
include::{snippets}/hello/http-response.adoc[]

这是我的配置文件。

maven 依赖关系

<dependencies>

    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>${junit.jupiter.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web-services</artifactId>
    </dependency>
    <!-- Add Log4j2 Dependency -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-log4j2</artifactId>
    </dependency>
    <!-- Needed for Async Logging with Log4j 2 -->
    <dependency>
        <groupId>com.lmax</groupId>
        <artifactId>disruptor</artifactId>
        <version>${disruptor.version}</version>
    </dependency>


    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <exclusions>
            <exclusion>
                <groupId>junit</groupId>
                <artifactId>junit</artifactId>
            </exclusion>
        </exclusions>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>${asciidoctor.version}</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <sourceHighlighter>prettify</sourceHighlighter>
                        <attributes>
                            <toc>left</toc>
                            <icons>font</icons>
                            <sectanchors>true</sectanchors>
                            <idprefix/>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>org.springframework.restdocs</groupId>
                    <artifactId>spring-restdocs-asciidoctor</artifactId>
                    <version>${spring-restdocs.version}</version>
                </dependency>
            </dependencies>
        </plugin>
        <plugin>
            <artifactId>maven-resources-plugin</artifactId>
            <version>${maven-resources-plugin.version}</version>
            <executions>
                <execution>
                    <id>copy-resources</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>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <dependencies>
                <dependency>
                    <groupId>org.junit.platform</groupId>
                    <artifactId>junit-platform-surefire-provider</artifactId>
                    <version>${junit.platform.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

这是index.adoc

= blog
:doctype: book
:icons: font
:source-highlighter: highlightjs

== /hello: Say "Hello World!"

operation::hello[]

.request
include::{snippets}/hello/http-request.adoc[]

.response
include::{snippets}/hello/http-response.adoc[]

这是我的测试class

@SpringBootTest
@AutoConfigureMockMvc
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class HelloControllerTest {
    private MockMvc mockMvc;

    @BeforeEach
    public void setUp(WebApplicationContext webApplicationContext,
                      RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(restDocumentation))
                .build();
    }

    @Test
    public void hello() throws Exception {

        mockMvc.perform(get("/hello").param("name", "imckh"))
                .andExpect(status().isOk())
                .andDo(print())
                .andExpect(jsonPath("$.msg", "Hello imckh!").exists())
                .andDo(document("hello",
                        requestParameters(parameterWithName("name").description("The name to retrieve")),
                        responseFields(
                                fieldWithPath("code").description("Code of the response"),
                                fieldWithPath("msg").description("Message of the response"))
                ));
    }
}

当我完成测试时，它可以生成一些 *.adoc 文件，例如 'http-request.adoc, http-response.adoc'， generated-snippets 然后我使用 maven 包，它确实可以生成一个 index.html，但它不能在下面解析

operation::hello[]

.request
include::{snippets}/hello/http-request.adoc[]

.response
include::{snippets}/hello/http-response.adoc[]

generated docs

这一步出错：Including multiple snippets for an operation

谢谢。

Answer 1

您使用的 asciidoctor-maven-plugin 版本 2.0.0-RC.1 与 spring-restdocs-asciidoctor 不兼容。不幸的是，这种不兼容性导致无法解析生成的片段。如果你降级到 1.6.0，你至少会看到由于不兼容导致的失败。

您可以使用兼容 spring-restdocs-asciidoctor 的 asciidoctor-maven-plugin 的 1.5.x 版本来避免此问题。在撰写本文时，1.5.8 是最新版本。这个版本一切正常。

您可能也对 this Spring REST Docs issue 感兴趣，一旦尘埃落定，它有望弄清楚如何处理 AsciidoctorJ 中的重大变化。