Spring Rest Doc not producing html

Question

I followed the getting started guide for Spring Rest Doc word by word, but I cannot get any html out of the generated snippets.

The snippets are generated fine in the directory I configure (build/generated-snippets), but I can't see any html5/ directory with html files generated out of the snippets.

The doc at some point says what to do to package the documentation in the jar, and it's clear that it expects some files in an html5/ directory, but this is not created when the build runs:

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

What am I missing?

My project files, 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'
}

and a simple test file I use to test:

@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"));
    }

}

Shore

Do you have a hand-written .adoc file that is including the generated snippets? Also, how are you running your build? You need to run the asciidoctor task to produce the HTML from the .adoc file(s) and snippets. – Postmaster

I don't have an hand-written adoc. I thought I needed one but I am not sure where to put this in order to be picked up? The documentation is a bit unclear on this. After digging in the asciiidoc gradle plugin code I tried to change what the documentation says at point 4 (changed inputs.dir to sourceDir) and I can see html files now in build/asciidoc/html, is this a doc mistake? – Shore

No, it's not a mistake. Setting the generated snippets directory as an output of the test task and an input of the asciidoctor task allows Gradle to figure out task dependencies and perform accurate up-to-date checks. – Postmaster

Answer 1

Create an .adoc file (like api-guide.adoc) under src/main/asciidoc (Maven) or src/docs/asciidoc (Gradle) with reference to the generated snippets . Then the html will be generated in the specified directory .

Velure

If I do that, still no html is produced. If I change the build.gradle file in the asciidoctor section (inputs.dir changed to sourceDir) I can see some html produced from the generated snippets in build/asciidoc/html, but not the one for the api-guide.adoc I just created in src/main/asciidoc. – Shore

The Asciidoctor Gradle plugin looks in src/docs/asciidoc by default so that's where your hand-written .adoc file should go. – Postmaster

I have the same problem. The .adoc document in the right place but still no html. – Cambogia

what means 'generated in the specified directory'? Where is it specified? It ain't the 'src/main/asciidocs' folder, is it? – Boogeyman

@DirkSchumacher by specified directory he means build/asciidoc/html5. I am assuming you have followed the documentation as it is. – Stenson

Answer 2

use: {spring-restdocs.version} in place of {project-version} then update project.

It'll look something like this,

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

After that, Project > right-click > maven > update-project.

Then re-build the project. hope this will solve your problem.

Sweetandsour