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).
For Java 9/10/11 support, use spring-auto-restdocs-json-doclet-jdk9
as doclet dependency.