docs: adds instructions for debugging Groovy scripts.

Author: outofcoffee

docs/groovy_debugging.md

@@ -0,0 +1,50 @@
+# Debugging Groovy scripts
+
+You can attach a debugger to the JVM to step through your Groovy scripts, inspect variables etc.
+
+The key steps involved are:
+
+1. Enable the JVM debugger, listening on a local port
+2. Start Imposter
+3. Connect to the debug port
+
+## Enable the JVM debugger
+
+Enable the JVM debugger with the following environment variable:
+
+    JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000"
+
+> **Note**
+> Here we have set the debug port to 8000.
+
+### Docker users
+
+When running in Docker, make sure to expose the debug port.
+
+For example:
+
+```bash
+docker run --rm -it -p8080:8080 -p8000:8000 -v $PWD:/opt/imposter/config outofcoffee/imposter
+```
+
+> In this example, port 8000 is exposed along with the regular port, 8080.
+
+## Steps for IntelliJ IDEA
+
+These steps will explain how to connect your IDE's debugger to the debug port.
+
+In IntelliJ, create a simple project pointing to the directory containing your script file.
+
+In the following steps, we will add a new run configuration, start your mock and attach the debugger.
+
+### Step-by-step
+
+1. Add a 'Remote JVM Debug' run configuration:
+   ![groovy_jvm_debug_config.png](images/groovy_jvm_debug_config.png)
+2. Set the `Port` to the same value as the debug configuration.
+3. Start Imposter and wait for the server to be ready.
+4. In IntelliJ start the run configuration in Debug mode, which will connect the debugger to the Imposter JVM.
+
+Set breakpoints in the script file as normal. When your script is invoked in Imposter, the debugger will pause on breakpoints and you can evaluate variables in scope.
+
+![groovy_debug.png](images/groovy_debug.png)

docs/groovy_tips.md

@@ -4,6 +4,10 @@
 
 This section provides additional tips and tricks when using Groovy as the scripting language for your mocks. It builds on the [Scripting](./scripting.md) documentation. If you are new to Imposter scripting, it's best to start there.
 
+## Debugging Groovy scripts
+
+See the [debugging Groovy scripts](./groovy_debugging.md) documentation.
+
 ## Block syntax for `respond`
 
 Groovy users can use this special block syntax, for improved readability:
@@ -99,3 +103,15 @@ To do this:
 
 1. create a directory containing the JAR file
 2. set the `IMPOSTER_PLUGIN_DIR` environment variable (or set `plugin.dir` in your `.imposter.yaml` file in the config directory) to the path above
+
+## Improved Groovy DSL support in your IDE
+
+For more sophisticated script development, you can set up a project in your IDE with improved code assistance. You can use this alongside [the debugger](./groovy_debugging.md) for a fully integrated development experience.
+
+This requires setting up a project with a dependency on `imposter-api.jar` and adding the GroovyDSL (GDSL) file.
+
+➡️ [See an example project](https://github.com/outofcoffee/imposter/tree/main/examples/groovy-dsl)
+
+If you just want to download the GDSL file see:
+
+➡️ [Download the GDSL file](https://github.com/outofcoffee/imposter/tree/main/examples/groovy-dsl/src/main/resources/imposter.gdsl) 

docs/images/groovy_debug.png

@@ -265,5 +265,6 @@ This selects the example from the OpenAPI `examples` section for the API respons
 
 ## Further reading
 
-* [Tips and tricks for Groovy users](./groovy_tips.md)
+* [Tips and tricks for Groovy scripts](./groovy_tips.md)
+* [Debugging Groovy scripts](./groovy_debugging.md)
 * [Using modern JavaScript in scripts](./scripting_modern_js.md)