spring-restdocs: spring-restdocs-asciidoctor is incompatible with AsciidoctorJ 1.6 and later
Using the latest version (1.5.10) of the gradle plugin org.asciidoctor.convert causes the following exception to be thrown:
Exception in thread "main" java.lang.IncompatibleClassChangeError: Found interface org.asciidoctor.extension.JavaExtensionRegistry, but class was expected
at org.springframework.restdocs.asciidoctor.RestDocsExtensionRegistry.register(RestDocsExtensionRegistry.java:32)
at org.asciidoctor.extension.internal.ExtensionRegistryExecutor.registerAllExtensions(ExtensionRegistryExecutor.java:21)
at org.asciidoctor.internal.JRubyAsciidoctor.registerExtensions(JRubyAsciidoctor.java:113)
at org.asciidoctor.internal.JRubyAsciidoctor.processRegistrations(JRubyAsciidoctor.java:102)
at org.asciidoctor.internal.JRubyAsciidoctor.create(JRubyAsciidoctor.java:82)
at org.asciidoctor.internal.JRubyAsciidoctor.create(JRubyAsciidoctor.java:78)
at org.asciidoctor.Asciidoctor$Factory.create(Asciidoctor.java:713)
at org.asciidoctor.gradle.backported.AsciidoctorJavaExec.getAsciidoctorInstance(AsciidoctorJavaExec.groovy:71)
at org.asciidoctor.gradle.backported.AsciidoctorJavaExec.run(AsciidoctorJavaExec.groovy:39)
at org.asciidoctor.gradle.backported.AsciidoctorJavaExec.main(AsciidoctorJavaExec.groovy:194)
Using the previous version (1.5.9.2) works fine.
It would be a good idea I guess to release a new version of spring-restdocs that is built against the newest stable version of AsciidoctorJ (the gradle plugin currently uses AsciidoctorJ version 1.6.1, and the latest version is 1.6.2). Unfortunately, the Maven plugin still uses AsciidoctorJ version 1.5.8. Not sure if it’s possible to be compatible with the two versions.
About this issue
- Original URL
- State: closed
- Created 5 years ago
- Reactions: 4
- Comments: 28 (15 by maintainers)
Commits related to this issue
- Ensure that jars to be merged are built before merging them See gh-581 — committed to spring-projects/spring-restdocs by wilkinsona 5 years ago
- Reinstate javadoc and sources jars for spring-restdocs-asciidoctor See gh-581 — committed to spring-projects/spring-restdocs by wilkinsona 5 years ago
Here’s my feedback on the 2.0.4 snapshot release (I tested it with gradle 5.1).
I started by setting the version of the spring-restdocs-mockmvc and spring-restdocs-asciidoctor dependencies to 2.0.4.BUILD-SNAPSHOT.
So, @wilkinsona, everything works fine with the snapshot 👍 , with all the tested versions of the asciidoctor plugin, even though using the latest version needs adaptations (and thus changes to the spring-restdocs documentation)
Fixing the error is easy: the asciidoctor task must be modified to explicitly add the projectdir attribute:
Before:
After:
I tried running with
--warnings=allto know how to avoid using deprecated tasks. But there is no such option. The correct option is (I guess)--warning-mode=all. Running it with that option gives@ysb33r fixing the warning message to use the correct command line option would be nice.
So I tried using the plugin “org.asciidoctor.jvm.convert” instead of “org.asciidoctor.convert”. This plugin doesn’t create the
asciidoctorgradle configuration anymore, which is used to add the spring-restdocs-asciidoctor dependency. And the way to configure the asciidoctor task has changed. I managed to get everything working though, by applying the following changes (note: this uses the Gradle Kotlin DSL):After:
Also note that the generated html file is now located under
build/docs/asciidocinstead ofbuild/asciidoc/html5.@wilkinsona The READMEs on Asciidoctor Gradle for the various versions (1.5.x, 1.6.x, 2.x and 3.x) now contain notes w.r.t. to spring-restdocs compatibility. Basically it boils down to people should remain using 1.5.11 or 1.5.12 if they use spring-restdocs. Once the latter is upgraded to support AsciidoctorJ 2.0 (not 1.6) they will be able to use the 3.x range of asciidoctor-gradle. (In a similar note asciidoctor-maven 2.x).
Just to clarify the versioning on Asciidoctor Gradle:
Even though I am not a user of spring-restdocs, I am willing to help to get this resolved if someone of the Spring side can collaborate with me on this.
I’ve opened https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/385 to explore the possibility of the Maven plugin aligning its AsciidoctorJ dependency with that of the Gradle plugin.
@jzinet Also see asciidoctor/asciidoctor-gradle-plugin#404 regarding your Kotlin DSL discoveries.
@jzinet That has been fixed, but not released yet.
I’ve bitten the bullet and split things out into several modules so that I can compile against AsciidoctorJ 1.5, 1.6 and 2.0 and deal with their various incompatibles. The existing
spring-restdocs-asciidoctormodule then pulls these separate modules back together into a single jar that’s hopefully compatible with AsciidoctorJ 1.5, 1.6, and 2.0.Would a Kotlin DSL warrant such a release? I have one waiting to be reviewed 😉 See https://github.com/spring-projects/spring-restdocs/issues/547#issuecomment-466341352 and https://github.com/Ninja-Squad/spring-rest-docs-kotlin
Not yet, no. I’ve yet to have the time to figure out exactly what the right approach is going to be. Ideally, a maintenance release of REST Docs could add support for new versions of AsciidoctorJ but all the ways of achieving that [that I’ve thought of thus far] are pretty unpleasant. An alternative would be a new minor release of REST Docs that requires AsciidoctorJ 1.6, but with AsciidoctorJ 2.0 approaching, that’s only going to be a short-term solution.