update README.adoc

Author: Picazsoo

modules/openapi-generator-gradle-plugin/README.adoc

@@ -681,6 +681,67 @@ Run with --stacktrace option to get the stack trace. Run with --info or --debug
 $ ./gradlew openApiValidate --input=/Users/jim/projects/openapi-generator/modules/openapi-generator/src/test/resources/3_0/petstore.yaml
 ----
 
+=== Groovy DSL Bridge Methods
+
+Both project extensions and custom task instances provide bridge methods that allow Groovy DSL users to set file and directory properties using simple String paths. These bridge methods support both **method-style** and **property-style** syntax.
+
+==== Extension Bridge Methods (for openApiGenerate, openApiValidate, openApiMeta)
+
+When configuring project extensions like `openApiGenerate { }`, `openApiValidate { }`, or `openApiMeta { }`, Groovy DSL users can use bridge methods to set properties with String paths.
+
+.Available Extension Bridge Methods
+|===
+|Extension |Available Methods
+
+|`openApiGenerate`
+|`setInputSpec(path)`, `setOutputDir(path)`, `setTemplateDir(path)`, `setConfigFile(path)`, `setIgnoreFileOverride(path)`, `setInputSpecRootDirectory(path)`
+
+|`openApiValidate`
+|`setInputSpec(path)`
+
+|`openApiMeta`
+|`setOutputFolder(path)`
+|===
+
+.Example: Using extension bridge methods in Groovy DSL
+[source,groovy]
+----
+// Method-style syntax
+openApiGenerate {
+    generatorName.set("kotlin")
+    setInputSpec("$rootDir/specs/petstore.yaml")
+    setOutputDir("build/generated")
+    apiPackage.set("org.openapi.example.api")
+}
+
+// Property-style syntax (Groovy allows this syntactic sugar)
+openApiGenerate {
+    generatorName.set("kotlin")
+    inputSpec = "$rootDir/specs/petstore.yaml"
+    outputDir = "build/generated"
+    apiPackage.set("org.openapi.example.api")
+}
+
+// Also works with openApiValidate
+openApiValidate {
+    inputSpec = "$rootDir/specs/petstore.yaml"
+    recommend.set(true)
+}
+
+// And openApiMeta
+openApiMeta {
+    generatorName.set("MyGenerator")
+    outputFolder = "build/custom-generator"
+}
+----
+
+[IMPORTANT]
+====
+**Smart Input Routing:** The `setInputSpec()` method (in both extensions and tasks) automatically detects whether the provided path is a remote URL (e.g., `http://`, `https://`, `jar:`) or a local file path, and routes it to the appropriate property (`remoteInputSpec` or `inputSpec`).
+
+Additionally, when you set a local file path after previously setting a remote URL (or vice versa), the method automatically clears the conflicting property to prevent stale values from taking precedence. This ensures your configuration behaves predictably even when you change between local and remote specs.
+====
+
 === Generate multiple sources
 
 If you want to perform multiple generation tasks, you'd want to create a task that inherits from the `GenerateTask`.
@@ -716,6 +777,57 @@ task buildKotlinClient(type: org.openapitools.generator.gradle.plugin.tasks.Gene
 }
 ```
 
+==== Custom Task Bridge Methods (AsString suffix)
+
+When creating custom task instances (as shown above), Groovy DSL users also have access to bridge methods with the `AsString` suffix. These methods provide the same functionality as the extension bridge methods.
+
+[NOTE]
+====
+**Why the "AsString" suffix?**
+
+Due to technical limitations with Gradle's abstract property getters in task classes, the bridge methods for custom tasks require the `AsString` suffix to avoid naming conflicts with Gradle's internal getter methods.
+
+- **Extensions** (e.g., `openApiGenerate { }`) use methods like `setInputSpec()`, `setOutputDir()`
+- **Custom Tasks** (e.g., `task myTask(type: GenerateTask) { }`) use methods like `setInputSpecAsString()`, `setOutputDirAsString()`
+
+Both patterns work identically for String-based property configuration in Groovy DSL.
+====
+
+.Available AsString Bridge Methods for Custom Tasks
+|===
+|Task Type |Available Methods
+
+|`GenerateTask`
+|`setInputSpecAsString(path)`, `setOutputDirAsString(path)`, `setTemplateDirAsString(path)`, `setConfigFileAsString(path)`, `setIgnoreFileOverrideAsString(path)`, `setInputSpecRootDirectoryAsString(path)`, `setSchemaLocationAsString(path)`
+
+|`ValidateTask`
+|`setInputSpecAsString(path)`
+
+|`MetaTask`
+|`setOutputFolderAsString(path)`
+|===
+
+.Example: Using AsString methods in Groovy DSL
+[source,groovy]
+----
+// Method-style syntax
+task buildCustomClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
+    generatorName.set("kotlin")
+    setInputSpecAsString("$rootDir/specs/api.yaml")
+    setOutputDirAsString("build/generated/custom")
+    setTemplateDirAsString("templates/custom")
+    apiPackage.set("com.example.api")
+}
+
+// Property-style syntax (Groovy allows this syntactic sugar)
+task buildAnotherClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
+    generatorName.set("java")
+    inputSpecAsString = "$rootDir/specs/another-api.yaml"
+    outputDirAsString = "build/generated/another"
+    modelPackage.set("com.example.model")
+}
+----
+
 To execute your specs, you'd then do:
 
 ```
@@ -770,7 +882,16 @@ openApiGenerate {
 }
 ----
 
-*Note: Standard string assignments (e.g., `inputSpec = "path/to/file.yaml"`) are still fully supported via bridge methods for static files checked into your repository.*
+[NOTE]
+====
+**Provider API vs Bridge Methods:**
+
+For optimal lazy configuration and task wiring, both Groovy and Kotlin DSL users should use `.set()` with the Provider API when possible (e.g., `inputSpec.set(downloadSpec.flatMap { it.outputFile })`).
+
+For simpler cases with static String paths, Groovy DSL users can use the convenient bridge methods:
+- Extension configuration: Use methods like `setInputSpec()`, `setOutputDir()` (see "Extension Bridge Methods" section)
+- Custom task configuration: Use methods like `setInputSpecAsString()`, `setOutputDirAsString()` (see "Custom Task Bridge Methods" section)
+====
 
 == Troubleshooting