Adds metadata to contracts (#1466)

fixes #1340
fixes #1078 
fixes #1406

docs/src/main/asciidoc/_attributes.adoc

@@ -30,7 +30,7 @@
 :standalone_pact_path: {samples_path}/standalone/dsl
 :standalone_restdocs_path: {samples_path}/standalone/restdocs
 :tests_path: {core_path}/tests
-:samples_branch: 2.2.x
+:samples_branch: 3.0.x
 :samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/{samples_branch}
 :samples_code: https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/
 :doc_samples: {core_path}/samples/wiremock-jetty

docs/src/main/asciidoc/_project-features-contract.adoc

@@ -193,6 +193,7 @@ The following sections describe the most common top-level elements:
 * <<contract-dsl-ignoring-contracts>>
 * <<contract-dsl-in-progress>>
 * <<contract-dsl-passing-values-from-files>>
+* <<contract-dsl-metadata>>
 
 [[contract-dsl-description]]
 ==== Description
@@ -437,6 +438,40 @@ include::{contract_kotlin_spec_path}/src/test/resources/contracts/shouldWorkWith
 IMPORTANT: You should use this approach whenever you want to work with binary payloads,
 both for HTTP and messaging.
 
+[[contract-dsl-metadata]]
+==== Metadata
+
+You can add `metadata` to your contract. Via the metadata you can pass in configuration to extensions. Below you can find
+an example of using the `wiremock` key and value being WireMock's `StubMapping` object. Spring Cloud Contract is able to
+patch parts of your generated stub mapping with your custom code. You may want to do that in order to add webhooks, custom
+delays or integrate with third party WireMock extensions.
+
+====
+[source,groovy,indent=0,role="primary"]
+.groovy
+----
+include::{standalone_samples_path}/http-server/src/test/resources/contracts/fraud/shouldReturnFraudStats.groovy[tags=metadata,indent=0]
+----
+
+[source,yaml,indent=0,role="secondary"]
+.yml
+----
+include::{standalone_samples_path}/http-server/src/test/resources/contracts/yml/fraud/shouldReturnFraudStats.yml[tags=metadata,indent=0]
+----
+
+[source,java,indent=0,subs="verbatim,attributes",role="secondary"]
+.java
+----
+include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=metadata,indent=0]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.kotlin
+----
+include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=metadata,indent=0]
+----
+====
+
 [[features-http]]
 == Contracts for HTTP
 

docs/src/main/asciidoc/advanced.adoc

@@ -168,6 +168,54 @@ include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wirem
 ----
 ====
 
+[[customization-wiremock-from-metadata]]
+=== Customization of WireMock via Metadata
+
+With version 3.0.0 you're able to set `metadata` in your contracts. If you set an entry with key equal to `wiremock` and the value
+will be a valid WireMock's `StubMapping` JSON / map or an actual `StubMapping` object, Spring Cloud Contract will patch the generated
+stub with part of your customization. Let's look at the following example
+
+[source,yaml,indent=0]
+----
+include::{standalone_samples_path}/http-server/src/test/resources/contracts/yml/fraud/shouldReturnFraudStats.yml[tags=metadata,indent=0]
+----
+
+In the `metadata` section we've set an entry with key `wiremock` and its value is a JSON `StubMapping` that sets a delay in the generated stub. Such code allowed us to get the following merged WireMock JSON stub.
+
+[source,json,indent=0]
+----
+{
+  "id" : "ebae49e2-a2a3-490c-a57f-ba28e26b81ea",
+  "request" : {
+    "url" : "/yamlfrauds",
+    "method" : "GET"
+  },
+  "response" : {
+    "status" : 200,
+    "body" : "{\"count\":200}",
+    "headers" : {
+      "Content-Type" : "application/json"
+    },
+    "fixedDelayMilliseconds" : 2000,
+    "transformers" : [ "response-template" ]
+  },
+  "uuid" : "ebae49e2-a2a3-490c-a57f-ba28e26b81ea"
+}
+----
+
+The current implementation allows to manipulate only the stub side (we don't change the generated test). Also, what does not get changed
+are the whole request and body and headers of the response.
+
+[[customization-wiremock-from-metadata-custom-processor]]
+==== Customization of WireMock via Metadata and a Custom Processor
+
+If you want to apply a custom WireMock `StubMapping` post processing, you can under `META-INF/spring.factories` under the
+`org.springframework.cloud.contract.verifier.converter.StubProcessor` key register your own implementation of a stub processor. For your convenience we've created an interface called `org.springframework.cloud.contract.verifier.wiremock.WireMockStubPostProcessor` that is dedicated to WireMock.
+
+You'll have to implement methods to inform Spring Cloud Contract whether the post processor is applicable for a given contract and how should the post processing look like.
+
+IMPORTANT: On the consumer side, when using Stub Runner, remember to pass the custom `HttpServerStubConfigurer` implementation (e.g. the one that extends `WireMockHttpServerStubConfigurer`) where you'll register a custom extension of your choosing. If you don't do so, even you have a custom WireMock extension on the classpath, WireMock will not notice it, won't apply it and will print out a warning statement that the given extension was not found.
+
 [[customization-pluggable-architecture]]
 == Using the Pluggable Architecture
 

docs/src/test/resources/contract.yml

@@ -57,3 +57,15 @@ response:
         regex: bar
       - key: foo3
         predefined:
+metadata:
+  wiremock:
+    "postServeActions": {
+      "webhook": {
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "method": "POST",
+        "body": "{ \"result\": \"SUCCESS\" }",
+        "url": "http://localhost:56299/callback"
+      }
+    }