Задача jsonDoclet: не удалось создать документ Javadoc

Я пытаюсь настроить spring-auto-restdocs в своем проекте, который использует JDK 11, Gradle 5, JUnit5 и Spring Webflux с весенней загрузкой 2.1.1.

Я следовал обычному руководству по установке spring-restdocs здесь: https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

Затем также сделал это руководство по началу работы: https://scacap.github.io/spring-auto-restdocs/

Моя проблема в том, что когда я пытаюсь запустить следующую команду gradle: gradlew asciidoctor --stacktrace

Я получаю следующую ошибку:

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

У меня есть следующие соответствующие конфигурации:

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
}

Базовый тестовый класс:

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

Spring-auto-restdocs не работает с этой настройкой или я что-то упустил? Мы очень признательны за любую помощь (особенно от наших тестеров, которые, наконец, получат какую-то достойную документацию по API: D, к сожалению, Springfox не работает с функциональной маршрутизацией webflux).


person Zoltán Umlauf    schedule 06.08.2019    source источник


Ответы (1)


Для поддержки Java 9/10/11 используйте spring-auto-restdocs-json-doclet-jdk9 в качестве зависимости doclet.

person Juraj Misur    schedule 29.08.2019
comment
Мне не нужно какое-то время, чтобы попробовать это, но спасибо за совет! это могло быть причиной того, что вся документация по автоматическому отдыху на самом деле не работала - person Zoltán Umlauf; 29.08.2019