spring-boot - jsonDoclet 任务 : Javadoc generation failed

标签 spring-boot junit5 spring-restdocs spring-auto-restdocs

我正在尝试在我的项目中设置 spring-auto-restdocs,该项目使用 JDK 11、Gradle 5、JUnit5 和 Spring Webflux 以及 spring boot 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 的功能路由)。

最佳答案

对于 Java 9/10/11 支持,请使用 spring-auto-restdocs-json-doclet-jdk9作为 doclet 依赖项。

关于spring-boot - jsonDoclet 任务 : Javadoc generation failed,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/57370847/

相关文章:

java - 在 Spring Boot 中处理重定向的正确方法是什么?

google-app-engine - Spring Boot App Engine 日志消息未显示

java - 在 Reactor 应用程序中测试对 Flux 的背压应用

java - maven:无法运行junit5-jupiter-starter-maven?

java - Spring REST 模拟上下文路径

spring-boot - OpenAPI 规范 3.0 在浏览器和服务器下拉列表中显示不同的 url

java - 使用 JUnit5 的集成测试用例不适用于 URL 中包含大括号的 get 请求

java - Ashot Java 堆空间错误

java - Spring REST Doc未命名请求参数

java - Spring Restdocs 响应负载包含可选的空对象列表