为什么代码片段包含 spring-restdocs-asciidoctor 的错误?

Question

当我将 spring-restdocs 与 ASCIIdoctor一起使用时.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"， 生成的代码段 然后我使用maven包，它确实可以生成一个index.html，但它无法在下面解析

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

生成的文档

在此步骤中出错：为操作包含多个代码段

谢谢。

Answer 1

您正在使用与spring-restdocs-asciidoctor不兼容的asciidoctor-maven-plugin的 2.0.0-RC.1 版本。遗憾的是，这种不兼容会导致以静默方式解析生成的代码段。如果降级到1.6.0，则至少会看到由不兼容引起的故障。

您可以通过使用spring-restdocs-asciidoctor兼容的 1.5.x 版本的asciidoctor-maven-plugin来避免此问题。在撰写本文时，1.5.8 是最新版本。在此版本中，事情按预期工作。

您可能还对这个Spring REST Docs问题感兴趣，一旦尘埃落定，它有望弄清楚如何处理AsciidoctorJ中的重大更改。