Document how to use REST Docs with the new org.asciidoctor.jvm.convert Gradle plugin

spring-restdocs-asciidoctor seems that it doesn’t support the latest asciidoctor plugin.

Here is my config.

/*id 'org.asciidoctor.jvm.convert' version '3.2.0'*/
id 'org.asciidoctor.convert' version '2.4.0'

/* for rest docs */
ext {
    set('snippetsDir', file('build/generated-snippets'))
    set('spring-restdocs.version', '2.0.4.RELEASE')
}

/* for rest docs */
testImplementation "org.springframework.restdocs:spring-restdocs-webtestclient:${project.ext['spring-restdocs.version']}"
asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"

test {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

asciidoctor {
    attributes 'snippets': snippetsDir
    inputs.dir snippetsDir
    dependsOn test
}

bootJar {
    dependsOn asciidoctor
    from("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

gradle clean

13:01:39: Executing task 'clean'...

Configuration on demand is an incubating feature.

> Configure project :
You are using one or more deprecated Asciidoctor Gradle plugin features.
These will be removed in 3.0 of these plugins.
To help you migrate we have compiled some tips for you based upon your current usage.
- org.asciidoctor.convert:
  - 'org.asciidoctor.convert' is deprecated. When you have time please switch over to 'org.asciidoctor.jvm.convert'.
  - jcenter() is no longer added by default. If you relied on this behaviour in the past, please add jcenter() to the repositories block.



> Task :clean

BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed
13:01:41: Task execution finished 'clean'.

gradle build

13:06:44: Executing task 'build'...

Configuration on demand is an incubating feature.

> Configure project :
You are using one or more deprecated Asciidoctor Gradle plugin features.
These will be removed in 3.0 of these plugins.
To help you migrate we have compiled some tips for you based upon your current usage.
- org.asciidoctor.convert:
  - 'org.asciidoctor.convert' is deprecated. When you have time please switch over to 'org.asciidoctor.jvm.convert'.
  - jcenter() is no longer added by default. If you relied on this behaviour in the past, please add jcenter() to the repositories block.



> Task :compileJava FROM-CACHE
> Task :processResources
> Task :classes
> Task :compileTestJava FROM-CACHE
> Task :processTestResources NO-SOURCE
> Task :testClasses UP-TO-DATE
> Task :test FROM-CACHE

> Task :asciidoctor
Property 'logDocuments' is annotated with @Optional that is not allowed for @Console properties. This behaviour has been deprecated and is scheduled to be removed in Gradle 7.0. See https://docs.gradle.org/6.3/userguide/more_about_tasks.html#sec:up_to_date_checks for more details.
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.codehaus.groovy.reflection.CachedClass (file:/C:/Users/purpl/.gradle/wrapper/dists/gradle-6.3-all/b4awcolw9l59x95tu1obfh9i8/gradle-6.3/lib/groovy-all-1.3-2.5.10.jar) to method java.lang.Object.finalize()
WARNING: Please consider reporting this to the maintainers of org.codehaus.groovy.reflection.CachedClass
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

> Task :bootJar
> Task :jar SKIPPED
> Task :assemble
> Task :check UP-TO-DATE
> Task :build

BUILD SUCCESSFUL in 13s
6 actionable tasks: 3 executed, 3 from cache
13:06:58: Task execution finished 'build'.

[wilkinsona]

Thanks. That’s a problem in your build.gradle rather than with REST Docs. As noted in the Asciidoctor Gradle plugin’s documentation, the asciidoctor configuration is not created by default if you use the org.asciidoctor.jvm.convert plugin. You need to define a configuration and then configure the asciidoctor task to use it:

configurations {
    asciidoctorExt
}

dependencies {
    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    // …
}

asciidoctor {
    configurations 'asciidoctorExt'
    // …
}

We can use this issue to track making some updates to REST Docs’ documentation to show how the newer Asciidoctor Gradle plugin should be configured.

[wilkinsona]

Closing in favor of #744.