Snippet from operation macro not found with asciidoctor-maven-plugin v3.1.0

[sephiroth-j]

After upgrading asciidoctor-maven-plugin from 3.0.0 to 3.1.0 (or 3.1.1) the operation macro seems to be broken. The referenced snippets cannot be found, but they are present and not empty.

example
A file src/main/asciidoc/demo.adoc with the content

= Demo

operation::foo/bar[snippets='curl-request,request-body,response-body,response-fields']

will result in the following warning when generating the document.

asciidoctor: WARN: demo.adoc: line 3: Snippet curl-request not found at ..\..\..\target\generated-snippets/foo/bar/curl-request.adoc for operation foo/bar
asciidoctor: WARN: demo.adoc: line 3: Snippet request-body not found at ..\..\..\target\generated-snippets/foo/bar/request-body.adoc for operation foo/bar
asciidoctor: WARN: demo.adoc: line 3: Snippet response-body not found at ..\..\..\target\generated-snippets/foo/bar/response-body.adoc for operation foo/bar
asciidoctor: WARN: demo.adoc: line 3: Snippet response-fields not found at ..\..\..\target\generated-snippets/foo/bar/response-fields.adoc for operation foo/bar

env
openjdk version "21.0.4" 2024-07-16 LTS
OpenJDK Runtime Environment Temurin-21.0.4+7 (build 21.0.4+7-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.4+7 (build 21.0.4+7-LTS, mixed mode, sharing)
Windows 10 x64
Maven 3.9.9

[wilkinsona]

Thanks for the report.

This appears to be due to a breaking change in the Asciidoctor Maven Plugin. With 3.0.0, the working directory when the operation macro is invoked is the directory that contains the .adoc file that's being processed. In 3.1.0, the working directory has changed and is the root of the Maven project that's being built. This change means that the relative paths used to find the generated snippets no longer work.

I'll investigate further to see if REST Docs can reliably tolerate the different behaviors of the Asciidoctor Maven Plugin or if that plugin will have to be changed to restore its old behavior.

In the meantime, you can work around the problem by configuring the snippets attribute in your pom.xml when you declare the dependency on the Asciidoctor Maven plugin within its <configuration>:

<attributes>
    <snippets>${basedir}/target/generated-snippets</snippets>
</attributes>

[wilkinsona]

The breaking change is actually in AsciidoctorJ. In 3.1.0, the Asciidoctor Maven Plugin upgraded to 3.0.0 from 2.5.x. Downgrading back to 2.5.11 by adding a <dependency> on org.asciidoctor:asciidoctorj:2.5.11 to the asciidoctor-maven-plugin declaration also works around the problem.

[wilkinsona]

We can fix this in REST Docs. While investigating, I've discovered that when using Gradle the snippets attribute is set to an absolute path by default. When using Maven, it's set to a path that's relative to the docdir. The former works correctly, irrespective of the working directory. The latter assumes that the working directory will be the docdir which doesn't hold true when using AsciidoctorJ 3. This explains why the problem only occurs with Maven and also shows that we should be able to fix it by always returning an absolute path when resolving the default value for the snippets attribute.

[sephiroth-j]

Thanks for the quick fix and the workaround.