Spring REST Docs - 如何配置 asciidoctor 任务以将生成的片段包含到索引中？答案

【问题标题】：Spring REST Docs - how to configure asciidoctor task to include generated snippet into index?Spring REST Docs - 如何配置 asciidoctor 任务以将生成的片段包含到索引中？
【发布时间】：2018-03-10 11:20:52
【问题描述】：

我有一个index.adoc 文件位于： src/docs/asciidoc/index.adoc

含内容：include::{snippets}/add-measurement/curl-request.adoc[]

当我调用构建任务时，生成的 sn-ps 在这里：build/generated-snippets/my-call/*.adoc

但是当我查看生成的 index.html 时，结果发现 sn-ps 不包括在内：

Unresolved directive in index.adoc - include::{snippets}/add-measurement/curl-request.adoc[]

build.gradle 中我的asciidoctor 任务：

asciidoctor {
    dependsOn junitPlatformTest
}

当我将sourceDir snippetsDir 添加到asciidoctor gradle 任务时，每个sn-p 都会转换为html，但不会生成index.html。

【问题讨论】：

标签： junit5 asciidoctor spring-restdocs

【解决方案1】：

根据您的信息，snippetsDir 已配置并且 sn-ps 放置在预期的文件夹中，AsciiDoctor sourceDir 已经正确，因为生成了 index.html（但包含损坏的包含）。所以似乎缺少的一件事是将snippetDir 传递给AsciiDoctor：

asciidoctor {
  inputs.dir snippetsDir
  dependsOn junitPlatformTest  
}

或

asciidoctor {
  attributes "snippets": snippetsDir
  dependsOn junitPlatformTest  
}

Gradle 设置示例：

【讨论】：

如果您使用提供 Asciidoctor 扩展的spring-restdocs-asciidoctor 模块，则应自动设置snippets 属性。不幸的是，在 Asciidoctor Gradle 插件的 1.5.6 版中有一个bug，这意味着它在使用 Gradle 的守护程序时也不能可靠地工作。退回到 1.5.3 或禁用守护程序将解决问题。