Spring Rest Doc无法生成HTML。

Question

我逐字遵循了Spring Rest Doc的入门指南，但是我无法从生成的片段中获得任何html文件。

片段在我配置的目录（build/generated-snippets）中生成得很好，但我看不到任何html5/目录以从片段中生成的html文件。

文档在某个时候说要如何将文档打包到jar文件中，并且清楚地表明它期望在html5/目录中有一些文件，但是当构建运行时没有创建此目录。

dependsOn asciidoctor
from("${asciidoctor.outputDir}/html5") {
    into 'static/docs'
}

我应该注意什么？

我的项目文件，build.gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.springframework.boot:spring-boot-gradle-plugin:1.3.5.RELEASE'
    }
}

plugins {
    id 'org.asciidoctor.convert' version '1.5.2'
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'spring-boot'
apply plugin: 'jacoco'
apply plugin: 'war'

sourceCompatibility = 1.8
targetCompatibility = 1.8

ext { 
    snippetsDir = file('build/generated-snippets')
}

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web:1.3.5.RELEASE'
    compile 'org.springframework.boot:spring-boot-starter-logging:1.3.5.RELEASE'
    compile 'org.springframework.boot:spring-boot-starter-data-jpa:1.3.5.RELEASE'
    compile 'org.springframework.boot:spring-boot-starter-data-rest:1.3.5.RELEASE'
    compile 'org.springframework.cloud:spring-cloud-starter-aws:1.1.0.RELEASE'
    compile 'org.postgresql:postgresql:9.4.1208'
    compile 'commons-io:commons-io:2.5'

    testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:1.1.0.RELEASE'   
    testCompile 'org.springframework.restdocs:spring-restdocs-core:1.1.0.RELEASE'
    testCompile 'org.springframework.boot:spring-boot-starter-test:1.3.5.RELEASE'
}

jacoco {
    toolVersion = "0.7.6.201602180812"
    reportsDir = file("$buildDir/customJacocoReportDir")
}

test {
    outputs.dir snippetsDir
    jacoco {
        append = false
        destinationFile = file("$buildDir/jacoco/jacocoTest.exec")
        classDumpFile = file("$buildDir/jacoco/classpathdumps")
    }
}

asciidoctor { 
    attributes 'snippets': snippetsDir 
    inputs.dir snippetsDir 
    dependsOn test 
}

war {
    dependsOn asciidoctor
    from("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }

    baseName = project_name
    version = version
    manifest {
        attributes(
            'Implementation-Title': project_name,
            'Implementation-Version': version
        )
    }
}

task wrapper(type: Wrapper) {
    gradleVersion = '2.13'
}

和我用来测试的简单测试文件：

@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = Application.class)
@WebAppConfiguration
public class ApiDocumentation
{
    @Rule
    public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");

    @Autowired
    private WebApplicationContext context;

    private MockMvc mockMvc;

    @Before
    public void setUp()
    {
        mockMvc = MockMvcBuilders.webAppContextSetup(context)
                .apply(documentationConfiguration(restDocumentation))
                .build();
    }

    @Test
    public void testIndex() throws Exception
    {
        mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(document("index"));
    }

}

- Francesco

---

您是否有手写的 .adoc 文件，其中包含生成的片段？另外，您是如何运行构建的呢？您需要运行 asciidoctor 任务来从 .adoc 文件和片段中生成 HTML。 - Andy Wilkinson

我没有手写的adoc文件。我以为我需要一个，但是我不确定应该把它放在哪里才能被捡起来？文档有点不清楚。在挖掘asciiidoc gradle插件代码后，我尝试更改文档所说的内容中的第4点（将inputs.dir更改为sourceDir），现在我可以看到html文件在build/asciidoc/html中了，这是文档错误吗？ - Francesco

不，这不是错误。将生成的片段目录设置为测试任务的输出和asciidoctor任务的输入，可以让Gradle找出任务依赖关系并执行准确的最新检查。 - Andy Wilkinson

Answer 1

在src/main/asciidoc（Maven）或src/docs/asciidoc（Gradle）下创建一个.adoc文件（例如api-guide.adoc），并参考生成的代码片段。 然后HTML将在指定目录中生成。

- Fahad Fazil

---

如果我这样做，仍然没有生成HTML。如果我在asciidoctor部分的build.gradle文件中进行更改（将inputs.dir更改为sourceDir），则可以从build/asciidoc/html中生成一些HTML，但是无法生成我刚在src/main/asciidoc中创建的api-guide.adoc的HTML。 - Francesco

Asciidoctor Gradle插件默认查找src/docs/asciidoc目录，因此您手写的.adoc文件应放在该目录下。 - Andy Wilkinson

我有同样的问题。.adoc文档放在正确的位置，但仍然没有html。 - onnoweb

“在指定目录生成”是什么意思？它在哪里指定？不会是在“src/main/asciidocs”文件夹中吧？ - Dirk Schumacher

@DirkSchumacher所指的目录是build/asciidoc/html5。我假设您已经按照文档操作了。 - chaitanya guruprasad

Answer 2

使用：{spring-restdocs.version} 代替 {project-version}，然后更新项目。

它会看起来像这样：

dependencies {
    asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:{spring-restdocs.version}' 
    testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:{spring-restdocs.version}' 
}

之后，选择项目 > 右键 > maven > update-project。

然后重新构建项目。希望这能解决你的问题。

- ATOM