为什么代码段包含了spring-restdocs-asciidoctor的错误？

Question

当我使用带有asciidoctor的spring-restdocs时，我确实可以生成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[]

这是我的测试类

@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

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

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

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