jsonDoclet task: Javadoc generation failed

Question

I am trying to setup spring-auto-restdocs in my project, which uses JDK 11, Gradle 5, JUnit5 and Spring Webflux with spring boot 2.1.1.

I've followed the normal spring-restdocs setup guide here: https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

Then also did this getting started guide: https://scacap.github.io/spring-auto-restdocs/

My problem is that when I try to run the following gradle command: gradlew asciidoctor --stacktrace

I get the following error:

javadoc: warning - The old Doclet and Taglet APIs in the packages
com.sun.javadoc, com.sun.tools.doclets and their implementations
are planned to be removed in a future JDK release. These
components have been superseded by the new APIs in jdk.javadoc.doclet.
Users are strongly recommended to migrate to the new APIs.
javadoc: error - invalid flag: -d
//Skipped javadoc usage helper here

* What went wrong:
Execution failed for task ':jsonDoclet'.
> Javadoc generation failed. Generated Javadoc options file (useful for troubleshooting): 'C:\Code\EMOB\ocpi-credential\build\tmp\jsonDoclet\javadoc.options'

* Try:
Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':jsonDoclet'.
        at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter$3.accept(ExecuteActionsTaskExecuter.java:148)
        at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter$3.accept(ExecuteActionsTaskExecuter.java:145)
        at org.gradle.internal.Try$Failure.ifSuccessfulOrElse(Try.java:191)
        at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter.execute(ExecuteActionsTaskExecuter.java:138)
        //Skipped a lot of stacktrace here
Caused by: org.gradle.api.GradleException: Javadoc generation failed. Generated Javadoc options file (useful for troubleshooting): 'C:\Code\EMOB\ocpi-credential\build\tmp\jsonDoclet\javadoc.options'
        at org.gradle.api.tasks.javadoc.internal.JavadocGenerator.execute(JavadocGenerator.java:58)
        at org.gradle.api.tasks.javadoc.internal.JavadocGenerator.execute(JavadocGenerator.java:31)
        at org.gradle.api.tasks.javadoc.Javadoc.executeExternalJavadoc(Javadoc.java:158)
        at org.gradle.api.tasks.javadoc.Javadoc.generate(Javadoc.java:146)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
        at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        //Skipped a lot of stacktrace here
Caused by: org.gradle.process.internal.ExecException: Process 'command 'C:\Program Files\Java\jdk-11.0.2\bin\javadoc.exe'' finished with non-zero exit value 1
        at org.gradle.process.internal.DefaultExecHandle$ExecResultImpl.assertNormalExitValue(DefaultExecHandle.java:396)
        at org.gradle.process.internal.DefaultExecAction.execute(DefaultExecAction.java:37)
        at org.gradle.api.tasks.javadoc.internal.JavadocGenerator.execute(JavadocGenerator.java:53)
        ... 93 more

I have the following relevant configurations:

build.gradle

buildscript {
    ext {
        springBootVersion = '2.1.1.RELEASE'
        junitVersion = '5.3.1'
        snippetsDir = file("$buildDir/generated-snippets")
        javadocJsonDir = file("$buildDir/generated-javadoc-json")
    }
    repositories {
        mavenCentral()
        maven { url "https://plugins.gradle.org/m2/" }
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
        classpath "org.jfrog.buildinfo:build-info-extractor-gradle:latest.release"
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
    }
}

configurations {
    jsondoclet
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'
apply plugin: "com.jfrog.artifactory"
apply plugin: 'org.asciidoctor.convert'


group = 'hu.emobiliti'
version = '1.0'
sourceCompatibility = 11

dependencies {
    testImplementation(
            "org.springframework.boot:spring-boot-starter-test",
            "org.junit.jupiter:junit-jupiter-api:$junitVersion",
            "org.junit.jupiter:junit-jupiter-params:$junitVersion",
            "org.junit.jupiter:junit-jupiter-engine:$junitVersion",
            "io.projectreactor:reactor-test",
            "org.testcontainers:mysql:1.11.4",
            "org.testcontainers:testcontainers:1.11.4",
            "org.springframework.restdocs:spring-restdocs-webtestclient:2.0.3.RELEASE",
            "capital.scalable:spring-auto-restdocs-core:2.0.6"
    )
    asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.3.RELEASE'
    jsondoclet group: 'capital.scalable', name: 'spring-auto-restdocs-json-doclet', version: '2.0.6'
}

task jsonDoclet(type: Javadoc, dependsOn: compileJava) {
    source = sourceSets.main.allJava
    classpath = sourceSets.main.compileClasspath
    destinationDir = javadocJsonDir
    options.docletpath = configurations.jsondoclet.files as List
    options.doclet = 'capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet'
    options.memberLevel = JavadocMemberLevel.PACKAGE
}

test {
    useJUnitPlatform()

    systemProperty 'org.springframework.restdocs.outputDir', snippetsDir
    systemProperty 'org.springframework.restdocs.javadocJsonDir', javadocJsonDir

    outputs.dir snippetsDir
    dependsOn jsonDoclet
}

asciidoctor {
    inputs.dir snippetsDir
    outputDir = file("src/docs/asciidoc")
    dependsOn test
}

jar {
    dependsOn asciidoctor
}

Base test class:

@WebFluxTest
@ExtendWith(RestDocumentationExtension.class)
public class HandlerBaseTest extends BaseTest {

    @Autowired
    protected ObjectMapper objectMapper;
    @Autowired
    protected WebTestClient testClient;
    @Autowired
    private ApplicationContext context;

    @BeforeEach
    protected void setUp(RestDocumentationContextProvider restDocumentation) {
        testClient = testClient
                .mutate()
                .responseTimeout(Duration.ofMillis(300000))
                .filter(documentationConfiguration(restDocumentation)
                                .snippets()
                                .withDefaults(WebTestClientInitializer.prepareSnippets(context),
                                              CliDocumentation.curlRequest(),
                                              HttpDocumentation.httpRequest(),
                                              HttpDocumentation.httpResponse(),
                                              AutoDocumentation.requestFields(),
                                              AutoDocumentation.responseFields(),
                                              AutoDocumentation.pathParameters(),
                                              AutoDocumentation.requestParameters(),
                                              AutoDocumentation.description(),
                                              AutoDocumentation.methodAndPath(),
                                              AutoDocumentation.section()))
                .build();
    }
}

Is spring-auto-restdocs does not play nicely with this setup or am I missing something? Any help is greatly appreciated (specially by our testers who would finally get some kind of decent api documentation :D sadly springfox does not work with the functional routing of webflux).

Answer 1

For Java 9/10/11 support, use spring-auto-restdocs-json-doclet-jdk9 as doclet dependency.