Add documentation that matchers are removing only part of request / response

fixes #383

docs/src/main/asciidoc/verifier/contract.adoc

@@ -567,6 +567,62 @@ and the WireMock stub like this:
 include::{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/springframework/cloud/contract/verifier/wiremock/DslToWireMockClientConverterSpec.groovy[tags=matchers,indent=0]
 ----
 
+IMPORTANT: If you use a `matcher` then the part of the request / response that the `matcher` is addressing
+via the JSON Path will get removed from assertion. In case of verifying a collection you have to create
+matchers for *all* elements of the collection.
+
+Let's look at the following example:
+
+[source,groovy,indent=0]
+----
+Contract.make {
+    request {
+        method 'GET'
+        url("/foo")
+    }
+    response {
+        status 200
+        body(events: [[
+                                 operation          : 'EXPORT',
+                                 eventId            : '16f1ed75-0bcc-4f0d-a04d-3121798faf99',
+                                 status             : 'OK'
+                         ], [
+                                 operation          : 'INPUT_PROCESSING',
+                                 eventId            : '3bb4ac82-6652-462f-b6d1-75e424a0024a',
+                                 status             : 'OK'
+                         ]
+                ]
+        )
+        testMatchers {
+            jsonPath('$.events[0].operation', byRegex('.+'))
+            jsonPath('$.events[0].eventId', byRegex('^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$'))
+            jsonPath('$.events[0].status', byRegex('.+'))
+        }
+    }
+}
+----
+
+This will lead in creating the following test (showing just the assertion section)
+
+[source,java,indent=0]
+----
+		and:
+			DocumentContext parsedJson = JsonPath.parse(response.body.asString())
+			assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("16f1ed75-0bcc-4f0d-a04d-3121798faf99")
+			assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("EXPORT")
+			assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("INPUT_PROCESSING")
+			assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("3bb4ac82-6652-462f-b6d1-75e424a0024a")
+			assertThatJson(parsedJson).array("['events']").contains("['status']").isEqualTo("OK")
+		and:
+			assertThat(parsedJson.read("\$.events[0].operation", String.class)).matches(".+")
+			assertThat(parsedJson.read("\$.events[0].eventId", String.class)).matches("^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})\$")
+			assertThat(parsedJson.read("\$.events[0].status", String.class)).matches(".+")
+----
+
+As you can see the assertion is malformed. That's because only the first element of the array got asserted.
+In order to fix this it's best to apply the assertion to the whole `$.events` collection and assert it
+via the `byCommand(...)` method.
+
 ==== JAX-RS support
 
 We support JAX-RS 2 Client API. Base class needs to define `protected WebTarget webTarget` and server initialization, right now the only option how to test JAX-RS API is to start a web server.