Raise the minimum supported version of AsciidoctorJ to 3.0

Closes gh-957

docs/src/docs/asciidoc/getting-started.adoc

@@ -78,6 +78,7 @@ If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a de
 <4> Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin.
 This will automatically configure the `snippets` attribute for use in your `.adoc` files to point to `target/generated-snippets`.
 It will also allow you to use the `operation` block macro.
+It requires AsciidoctorJ 3.0.
 
 [source,indent=0,subs="verbatim,attributes",role="secondary"]
 .Gradle
@@ -114,6 +115,7 @@ It will also allow you to use the `operation` block macro.
 <3> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` configuration.
 This will automatically configure the `snippets` attribute for use in your `.adoc` files to point to `build/generated-snippets`.
 It will also allow you to use the `operation` block macro.
+It requires AsciidoctorJ 3.0.
 <4> Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` configuration.
 If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead.
 <5> Configure a `snippetsDir` property that defines the output location for generated snippets.

docs/src/docs/asciidoc/working-with-asciidoctor.adoc

@@ -28,6 +28,7 @@ This section covers how to include Asciidoc snippets.
 
 You can use a macro named `operation` to import all or some of the snippets that have been generated for a specific operation.
 It is made available by including `spring-restdocs-asciidoctor` in your project's <<getting-started-build-configuration, build configuration>>.
+`spring-restdocs-asciidoctor` requires AsciidoctorJ 3.0.
 
 The target of the macro is the name of the operation.
 In its simplest form, you can use the macro to include all of the snippets for an operation, as shown in the following example:

spring-restdocs-asciidoctor/build.gradle

@@ -1,7 +1,6 @@
 plugins {
 	id "java-library"
 	id "maven-publish"
-	id "io.spring.compatibility-test" version "0.0.3"
 }
 
 description = "Spring REST Docs Asciidoctor Extension"
@@ -20,11 +19,3 @@ dependencies {
 
 	testRuntimeOnly("org.asciidoctor:asciidoctorj-pdf")
 }
-
-compatibilityTest {
-	dependency("AsciidoctorJ") { asciidoctorj ->
-		asciidoctorj.groupId = "org.asciidoctor"
-		asciidoctorj.artifactId = "asciidoctorj"
-		asciidoctorj.versions = ["3.0.0"]
-	}
-}

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessor.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2014-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import org.asciidoctor.ast.Document;
+import org.asciidoctor.extension.Preprocessor;
+import org.asciidoctor.extension.PreprocessorReader;
+import org.asciidoctor.extension.Reader;
+
+/**
+ * {@link Preprocessor} that sets defaults for REST Docs-related {@link Document}
+ * attributes.
+ *
+ * @author Andy Wilkinson
+ */
+final class DefaultAttributesPreprocessor extends Preprocessor {
+
+	private final SnippetsDirectoryResolver snippetsDirectoryResolver = new SnippetsDirectoryResolver();
+
+	@Override
+	public Reader process(Document document, PreprocessorReader reader) {
+		document.setAttribute("snippets", this.snippetsDirectoryResolver.getSnippetsDirectory(document.getAttributes()),
+				false);
+		return reader;
+	}
+
+}

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/RestDocsExtensionRegistry.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2024 the original author or authors.
+ * Copyright 2014-2023 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,9 +28,7 @@ public final class RestDocsExtensionRegistry implements ExtensionRegistry {
 
 	@Override
 	public void register(Asciidoctor asciidoctor) {
-		asciidoctor.rubyExtensionRegistry()
+		asciidoctor.javaExtensionRegistry().preprocessor(new DefaultAttributesPreprocessor());
-			.loadClass(RestDocsExtensionRegistry.class.getResourceAsStream("/extensions/default_attributes.rb"))
-			.preprocessor("DefaultAttributes");
 		asciidoctor.rubyExtensionRegistry()
 			.loadClass(RestDocsExtensionRegistry.class.getResourceAsStream("/extensions/operation_block_macro.rb"))
 			.blockMacro("operation", "OperationBlockMacro");

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2024 the original author or authors.
+ * Copyright 2014-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,14 +29,9 @@ import java.util.function.Supplier;
  *
  * @author Andy Wilkinson
  */
-public class SnippetsDirectoryResolver {
+class SnippetsDirectoryResolver {
 
-	/**
+	File getSnippetsDirectory(Map<String, Object> attributes) {
-	 * Returns the snippets directory derived from the given {@code attributes}.
-	 * @param attributes the attributes
-	 * @return the snippets directory
-	 */
-	public File getSnippetsDirectory(Map<String, Object> attributes) {
 		if (System.getProperty("maven.home") != null) {
 			return getMavenSnippetsDirectory(attributes);
 		}

spring-restdocs-asciidoctor/src/main/resources/extensions/default_attributes.rb

@@ -1,14 +0,0 @@
-require 'asciidoctor/extensions'
-require 'java'
-
-class DefaultAttributes  < Asciidoctor::Extensions::Preprocessor
-  
-  def process(document, reader)
-  	resolver = org.springframework.restdocs.asciidoctor.SnippetsDirectoryResolver.new()
-  	attributes = document.attributes
-  	attributes["snippets"] = resolver.getSnippetsDirectory(attributes) unless attributes.has_key?("snippets")
-  	false
-  end
-  
-end
- 

spring-restdocs-asciidoctor/src/test/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessorTests.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2014-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.restdocs.asciidoctor;
+
+import java.io.File;
+
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.Attributes;
+import org.asciidoctor.Options;
+import org.junit.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link DefaultAttributesPreprocessor}.
+ *
+ * @author Andy Wilkinson
+ */
+public class DefaultAttributesPreprocessorTests {
+
+	@Test
+	public void snippetsAttributeIsSet() {
+		String converted = createAsciidoctor().convert("{snippets}", createOptions("projectdir=../../.."));
+		assertThat(converted).contains("build" + File.separatorChar + "generated-snippets");
+	}
+
+	@Test
+	public void snippetsAttributeFromConvertArgumentIsNotOverridden() {
+		String converted = createAsciidoctor().convert("{snippets}",
+				createOptions("snippets=custom projectdir=../../.."));
+		assertThat(converted).contains("custom");
+	}
+
+	@Test
+	public void snippetsAttributeFromDocumentPreambleIsNotOverridden() {
+		String converted = createAsciidoctor().convert(":snippets: custom\n{snippets}",
+				createOptions("projectdir=../../.."));
+		assertThat(converted).contains("custom");
+	}
+
+	private Options createOptions(String attributes) {
+		Options options = Options.builder().build();
+		options.setAttributes(Attributes.builder().arguments(attributes).build());
+		return options;
+	}
+
+	private Asciidoctor createAsciidoctor() {
+		Asciidoctor asciidoctor = Asciidoctor.Factory.create();
+		asciidoctor.javaExtensionRegistry().preprocessor(new DefaultAttributesPreprocessor());
+		return asciidoctor;
+	}
+
+}

spring-restdocs-platform/build.gradle

@@ -15,8 +15,8 @@ dependencies {
 		api("org.apache.pdfbox:pdfbox:2.0.27")
 		api("org.apache.tomcat.embed:tomcat-embed-core:11.0.2")
 		api("org.apache.tomcat.embed:tomcat-embed-el:11.0.2")
-		api("org.asciidoctor:asciidoctorj:2.5.7")
+		api("org.asciidoctor:asciidoctorj:3.0.0")
-		api("org.asciidoctor:asciidoctorj-pdf:2.3.3")
+		api("org.asciidoctor:asciidoctorj-pdf:2.3.19")
 		api("org.assertj:assertj-core:3.23.1")
 		api("org.hamcrest:hamcrest-core:1.3")
 		api("org.hamcrest:hamcrest-library:1.3")