spring-restdocs

Spring Rest Doc (Gradle) Snippets disappear upon build


Recently switch to Gradle from Maven.

Following this tutorial for continuous REST Doc build with Gradle. https://www.youtube.com/watch?v=k5ncCJBarRI&t=1490s

Snippets are generating just fine when running test. Its when I am trying to generate asciidoc where it seems like the /build directory gets recreated without the snippets. So my generated html always shows

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

I am generating the asciidoc by the following command in the terminal

gradle asciidoctor -t

// Continuous build command
// Mentioned around @1:07:40 mark
// https://www.youtube.com/watch?v=k5ncCJBarRI&t=1490s

build.gradle

plugins {
    id 'org.springframework.boot' version '2.4.2'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'org.asciidoctor.convert' version '1.5.8'
    id 'java'
}

group = 'lab.restdocs'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '14'

repositories {
    mavenCentral()
}

ext {
    set('snippetsDir', file("build/generated-snippets"))
}

dependencies {

    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'junit:junit:4.12'

    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
}

test {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

asciidoctor {
    inputs.dir snippetsDir
    dependsOn test
}


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

MyTest

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureMockMvc
public class HelloControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Rule
    public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();


    @InjectMocks
    private HelloController helloController;

    @Mock
    private HelloService helloService;

    @Before
    public void setUp() throws Exception {
        // create a mock environment of helloController
        mockMvc = MockMvcBuilders.standaloneSetup(helloController)
                .apply(documentationConfiguration(this.restDocumentation))
                .build();

    }

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/hello/string"))
                .andDo(print())
                .andExpect(status().isOk())
                .andExpect(content().string(containsString("hello there"))
                )
                .andDo(document("home-string"));

    }

I also checked my build.gradle against https://spring.io/guides/gs/testing-restdocs/ and https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/#configuration-uris. I don't know what I am missing...

Thanks in advance.

Edited

Ran command gradle asciidoctor --console=plain

If it makes it easier I greated a Git repo https://github.com/erich5168/edu.rest-doc

 erichuang$ gradle asciidoctor --console=plain
> Task :compileJava
> Task :processResources
> Task :classes
> Task :compileTestJava
> Task :processTestResources NO-SOURCE
> Task :testClasses
> Task :test

> Task :asciidoctor
asciidoctor: WARNING: api.adoc: line 3: include file not found: /Users/erichuang/Desktop/JE/00-Development/dev/lab/lab-rest-docs/lab.restdocs-gradlebuild/build/generated-snippets/home/curl-request.adoc
asciidoctor: WARNING: api.adoc: line 5: include file not found: /Users/erichuang/Desktop/JE/00-Development/dev/lab/lab-rest-docs/lab.restdocs-gradlebuild/build/generated-snippets/home/http-request.adoc
asciidoctor: WARNING: api.adoc: line 7: include file not found: /Users/erichuang/Desktop/JE/00-Development/dev/lab/lab-rest-docs/lab.restdocs-gradlebuild/build/generated-snippets/home/http-response.adoc
asciidoctor: WARNING: api.adoc: line 20: include file not found: /Users/erichuang/Desktop/JE/00-Development/dev/lab/lab-rest-docs/lab.restdocs-gradlebuild/build/generated-snippets/home-json/http-response.adoc

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.5/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 2s
5 actionable tasks: 5 executed
Apples-MBP:lab.restdocs-gradlebuild erichuang$ 


Solution

  • When run from the command line, you build isn't running any tests. The tests aren't being run as your tests are using JUnit 4 while the test task has been configured to use the JUnit Platform (JUnit 5):

    test {
        outputs.dir snippetsDir
        useJUnitPlatform()
    }
    

    You can fix the problem either by updating your tests to use JUnit 5 or by removing useJUnitPlatform() from the test task's configuration so that it uses JUnit 4. The latter is the smaller change and leaves the test task looking like this:

    test {
        outputs.dir snippetsDir
    }