spring-restdocs-asciidoctor is incompatible with AsciidoctorJ 1.6 and later

[jnizet]

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.

[wilkinsona]

Ouch. Thanks for the report. I wonder how much in common the root cause of this and the root cause of spring-io/spring-asciidoctor-extensions#9 have in common? I'll see what I can do. Hopefully it'll be possible to be compatible with the two versions. I really don't want to have to have Maven- and Gradle-specific variants of the spring-restdocs-asciidoctor module.

[jnizet]

I guess the main problem here is actually the Maven asciidoctor plugin, which still uses 1.5.8. If it used 1.6.x as the gradle plugin does, a new version of Spring-REST-Docs could just depend on 1.6.x for everything.
The root cause is not the same, but it's similar: a huge binary incompatibility was introduced (the class JavaExtensionRegistry became an interface)

[wilkinsona]

I can work around the binary incompatibilities of JavaExtensionRegistry and RubyExtensionRegistry becoming interfaces by using reflection:

@Override
public void register(Asciidoctor asciidoctor) {
    try {
        Object javaExtensionRegistry = asciidoctor.getClass()
                .getMethod("javaExtensionRegistry").invoke(asciidoctor);
        javaExtensionRegistry.getClass().getMethod("preprocessor", Preprocessor.class)
                .invoke(javaExtensionRegistry, new DefaultAttributesPreprocessor());
        Object rubyExtensionRegistry = asciidoctor.getClass()
                .getMethod("rubyExtensionRegistry").invoke(asciidoctor);
        rubyExtensionRegistry.getClass().getMethod("loadClass", InputStream.class)
                .invoke(rubyExtensionRegistry, RestDocsExtensionRegistry.class
                        .getResourceAsStream("/extensions/operation_block_macro.rb"));
        rubyExtensionRegistry.getClass()
                .getMethod("blockMacro", String.class, String.class)
                .invoke(rubyExtensionRegistry, "operation", "OperationBlockMacro");
    }
    catch (Exception ex) {
        throw new IllegalStateException("Failed to register Asciidoctor extensions",
                ex);
    }
}

This moves things along, but a failure then occurs because the signature of DefaultAttributesPreprocessor is wrong. The process method used to be the following:

public abstract PreprocessorReader process(Document document, PreprocessorReader reader);

In AsciidoctorJ 1.6, it is now the following:

public void PreprocessorReader process(Document document, PreprocessorReader reader);

I can't implement those two methods in the same class, or even in the same module. This leaves me with a few choices:

1. Use something like ByteBuddy to generate the preprocessor at runtime
2. Merge modules together at build time as Spring Framework does for its Hibernate support
3. Provide separate spring-restdocs-asciidoctor modules for the different versions of AsciidoctorJ

I don't really like any of these, but I like 3 the least. It requires users to be aware of the differences and to figure out the right module to use. It's particularly bad as moving to a new patch release of Asciidoctor's Gradle plugin would require moving to a different variant of the spring-restdocs-asciidoctor module.

[wilkinsona]

I've opened asciidoctor/asciidoctor-maven-plugin#385 to explore the possibility of the Maven plugin aligning its AsciidoctorJ dependency with that of the Gradle plugin.

[abelsromero]

asciidoctor-maven-plugin 1.6.0 (using AsciidoctorJ 1.6.2) has been released.

However, this is a temporal fix.
At some point, rest-docs should adapt to support AsciidoctorJ (and maven & gradle) v2.x changes. Most notably maybe is the change in name of the SPI file.

Given AsciidoctorJ is still in Release candidate cycle, so maybe rest-docs v2.0.4 should hold to 1.6.x and start a 2.1.0 pointing to AsciidoctorJ 2.x, once a stable release is available?

[bric3]

@wilkinsona @abelsromero think about the spring restdocs 1.x users too that need a migration path to asciidoc 1.6 then 2.x but also a migration path to spring boot 2.x as well.

[bric3]

Any update on this ?

[wilkinsona]

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.

[bric3]

Yes, indeed, thanks @wilkinsona for the insight in this issue !