Gradle7 Kotlin DSL下升级Asciidoctor为jvm版本报错问询

两个报错的根因说明 #

• 第一个报错是因为新版org.asciidoctor.jvm.convert插件已经移除了默认注册的asciidoctor依赖配置，所以在dependencies块中调用asciidoctor()方法时找不到对应定义
• 第二个报错是因为新版插件的Asciidoctor任务API发生了变更，旧的配置写法和新的任务接收器类型不匹配

具体调整步骤 #

• 第一步：替换插件ID #

  将原有plugins块中的旧版插件声明，替换为新版插件，版本选择3.x+稳定版即可，示例：

  // 替换前：id("org.asciidoctor.convert") version "2.4.0"
  id("org.asciidoctor.jvm.convert") version "3.3.2"
  

• 第二步：新增自定义依赖配置 #

  在plugins块之后、dependencies块之前，新增asciidoctorExt配置声明，替代旧版默认的asciidoctor配置：

  val asciidoctorExt by configurations.creating
  

• 第三步：修改依赖声明 #

  将dependencies块中原有的asciidoctor开头的依赖，替换为asciidoctorExt开头：

  // 替换前：asciidoctor("org.springframework.restdocs:spring-restdocs-asciidoctor")
  asciidoctorExt("org.springframework.restdocs:spring-restdocs-asciidoctor")
  

• 第四步：调整asciidoctor任务配置 #

  修改原tasks.asciidoctor块，关联自定义的asciidoctorExt配置，同时适配新插件的API写法：

  tasks.asciidoctor {
      dependsOn(tasks.test)
      // 关联自定义依赖配置，加载spring-restdocs-asciidoctor的扩展能力
      configurations(asciidoctorExt)
      // 适配新插件的目录设置API
      sourceDir.set(file("src/main/docs"))
      inputs.dir(snippetsDir)
      attributes["snippets"] = snippetsDir
      attributes["docinfo1"] = ""
      attributes["environment-${project.properties["spring.profiles.active"]}"] = true
  }
  

完整修改后的配置示例 #

plugins {
    id("org.asciidoctor.jvm.convert") version "3.3.2"
    kotlin("jvm") version "1.5.0"
    kotlin("plugin.spring") version "1.5.0"
}

val asciidoctorExt by configurations.creating

repositories {
    mavenCentral()
    maven { url = uri("https://repo.spring.io/milestone") }
    maven { url = uri("https://repo.spring.io/snapshot") }
    jcenter()
}

dependencies {
    asciidoctorExt("org.springframework.restdocs:spring-restdocs-asciidoctor")
    // 其余原有依赖保持不变
}

val snippetsDir by extra { file("build/generated-snippets") }
tasks.test {
    useJUnitPlatform()
    outputs.dir(snippetsDir)
    mustRunAfter(tasks.flywayMigrate)
}

tasks.asciidoctor {
    dependsOn(tasks.test)
    configurations(asciidoctorExt)
    sourceDir.set(file("src/main/docs"))
    inputs.dir(snippetsDir)
    attributes["snippets"] = snippetsDir
    attributes["docinfo1"] = ""
    attributes["environment-${project.properties["spring.profiles.active"]}"] = true
}

内容的提问来源于stack exchange，提问作者MrAndre