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

}

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. — Andy Wilkinson, Jun 28 '16 at 07:52
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](http://docs.spring.io/spring-restdocs/docs/1.0.x/reference/html5/#getting-started-using-the-snippets) is a bit unclear on this. After digging in the asciiidoc gradle plugin code I tried to change [what the documentation says](http://docs.spring.io/spring-restdocs/docs/1.0.x/reference/html5/#getting-started-build-configuration-gradle) at point 4 (changed inputs.dir to sourceDir) and I can see html files now in build/asciidoc/html, is this a doc mistake? — Francesco, Jun 28 '16 at 10:34
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. — Andy Wilkinson, Jun 28 '16 at 12:55

score 10 · Accepted Answer · edited Jun 28 '16 at 13:04

10

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 .

edited Jun 28 '16 at 13:04

Andy Wilkinson

108,729
24
257
242

answered Jun 28 '16 at 10:46

Fahad Fazil

638
1
9
20

1

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`. – Francesco Jun 28 '16 at 11:11
1

The Asciidoctor Gradle plugin looks in `src/docs/asciidoc` by default so that's where your hand-written `.adoc` file should go. – Andy Wilkinson Jun 28 '16 at 12:50
2

I have the same problem. The .adoc document in the right place but still no html. – onnoweb Dec 05 '17 at 18:33
1

what means 'generated in the specified directory'? Where is it specified? It ain't the 'src/main/asciidocs' folder, is it? – Dirk Schumacher Feb 04 '19 at 10:36
@DirkSchumacher by specified directory he means `build/asciidoc/html5`. I am assuming you have followed the documentation as it is. – chaitanya guruprasad Apr 05 '21 at 09:52

score 0 · Answer 2 · edited Dec 16 '20 at 12:54

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.

Spring Rest Doc not producing html

2 Answers2

Linked