Added docs on extending the DSL

with this change we're explaining how you can add your custom methods to the DSL fixes #23
2016-11-21 11:46:01 +01:00
parent b1175ff9bd
commit 49373eb160
5 changed files with 105 additions and 11 deletions
--- a/README.adoc
+++ b/README.adoc
@@ -1033,7 +1033,7 @@ https://vimeo.com/130779882[click here to see the video]

 ==== Samples

-Here you can find some https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples/[samples].
+Here you can find some https://github.com/spring-cloud-samples/spring-cloud-contract-samples[samples].

 === FAQ

@@ -1552,12 +1552,13 @@ of either Gradle or Maven plugins.
 Here you can find interesting links related to Spring Cloud Contract Verifier:

 - https://github.com/spring-cloud/spring-cloud-contract/[Spring Cloud Contract Github Repository]
+- https://github.com/spring-cloud-samples/spring-cloud-contract-samples/[Spring Cloud Contract Samples]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html[Spring Cloud Contract Documentation]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/deprecated[Accurest Legacy Documentation]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#spring-cloud-contract-stub-runner[Spring Cloud Contract Stub Runner Documentation]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#stub-runner-for-messaging[Spring Cloud Contract Stub Runner Messaging Documentation]
 - https://gitter.im/spring-cloud/spring-cloud-contract[Spring Cloud Contract Gitter]
- https://github.com/spring-cloud/spring-cloud-contract[Spring Cloud Contract Maven Plugin]
+- https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/[Spring Cloud Contract Maven Plugin]

 == Documentation

--- a/docs/src/main/asciidoc/spring-cloud-contract.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-contract.adoc
@@ -4,8 +4,8 @@

 = Spring Cloud Contract

-_Documentation Authors: Adam Dudczak, Marcin Grzejszczak, Jakub Kubryński, Karol Lassak,
-Olga Maciaszek-Sharma, Mariusz Smykuła, Dave Syer, Mathias Düsterhöft_
+_Documentation Authors: Adam Dudczak, Mathias Düsterhöft, Marcin Grzejszczak, Jakub Kubryński, Karol Lassak,
+Olga Maciaszek-Sharma, Mariusz Smykuła, Dave Syer_

 {spring-cloud-version}

@@ -16,10 +16,10 @@ This project provides support for Consumer Driven Contracts and service schemas
 range of options for writing tests, publishing them as assets, asserting that a contract is kept by producers
 and consumers, for HTTP and message-based interactions.

-== Spring Cloud Contract Verifier
-
-include::verifier/spring-cloud-contract-verifier.adoc[]
-
 == Spring Cloud Contract WireMock

 include::spring-cloud-wiremock.adoc[]
+
+== Spring Cloud Contract Verifier
+
+include::verifier/spring-cloud-contract-verifier.adoc[]
--- a/docs/src/main/asciidoc/verifier/contract.adoc
+++ b/docs/src/main/asciidoc/verifier/contract.adoc
@@ -1,3 +1,5 @@
+:samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/master
+
 === Contract DSL

 IMPORTANT: Remember that inside the contract file you have to provide the fully qualified name to
@@ -313,4 +315,94 @@ as presented below (note you can use either `$` or `value` methods to provide `c
 [source,groovy]
 ----
 include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=consumer_producer]
----
+----
+
+=== Extending the DSL
+
+It is possible to provide your own functions to the DSL. The key requirement for this
+feature was to maintain the static compatibility. Below you will be able to see an example
+of:
+
+- creation of a JAR with reusable classes
+- referencing of these classes in the DSLs
+
+The full example can be found https://github.com/spring-cloud-samples/spring-cloud-contract-samples[here].
+
+==== Common JAR
+
+Below you can find three classes that we will reuse in the DSLs.
+
+*PatternUtils* contains functions used by both the **consumer** and the **producer**.
+
+[source,java]
+----
+include::{samples_url}/common/src/main/java/com/example/PatternUtils.java[]
+----
+
+*ConsumerUtils* contains functions used by the **consumer**.
+
+[source,java]
+----
+include::{samples_url}/common/src/main/java/com/example/ConsumerUtils.java[]
+----
+
+*ProducerUtils* contains functions used by the **producer**.
+
+[source,java]
+----
+include::{samples_url}/common/src/main/java/com/example/ProducerUtils.java[]
+----
+
+==== Adding the dependency to project
+
+In order for the plugins and IDE to be able to reference the common JAR classes you need
+to pass the dependency to your project.
+
+===== Test dependency in project's dependencies
+
+First add the common jar dependency as a test dependency. That way since your
+contracts files are available at test resources path, automatically the
+common jar classes will be visible in your Groovy files.
+
+====== Adding test dependency in Maven
+
+[source,xml]
+----
+include::{samples_url}/producer/pom.xml[tags=test_dep,indent=0]
+----
+
+====== Adding test dependency in Gradle
+
+[source,xml]
+----
+include::{samples_url}/producer/build.gradle[tags=test_dep,indent=0]
+----
+
+===== Test dependency in plugin's dependencies
+
+Now you have to add the dependency for the plugin to reuse at runtime.
+
+====== Adding test plugin dependency in Maven
+
+[source,xml]
+----
+include::{samples_url}/producer/pom.xml[tags=test_dep_in_plugin,indent=0]
+----
+
+====== Adding test plugin dependency in Gradle
+
+Inside your `buildscript { dependencies {} }` section pass the following:
+
+[source,groovy]
+----
+include::{samples_url}/producer/build.gradle[tags=test_dep_in_plugin,indent=0]
+----
+
+===== Referencing classes in DSLs
+
+Now you can reference your classes in your DSL. Example:
+
+[source,groovy]
+----
+include::{samples_url}/producer/src/test/resources/contracts/beer/rest/shouldGrantABeerIfOldEnough.groovy[indent=0]
+----
--- a/docs/src/main/asciidoc/verifier/introduction.adoc
+++ b/docs/src/main/asciidoc/verifier/introduction.adoc
@@ -497,7 +497,7 @@ https://vimeo.com/130779882[click here to see the video]

 ==== Samples

-Here you can find some https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples/[samples].
+Here you can find some https://github.com/spring-cloud-samples/spring-cloud-contract-samples[samples].

 === FAQ

--- a/docs/src/main/asciidoc/verifier/links.adoc
+++ b/docs/src/main/asciidoc/verifier/links.adoc
@@ -3,9 +3,10 @@
 Here you can find interesting links related to Spring Cloud Contract Verifier:

 - https://github.com/spring-cloud/spring-cloud-contract/[Spring Cloud Contract Github Repository]
+- https://github.com/spring-cloud-samples/spring-cloud-contract-samples/[Spring Cloud Contract Samples]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html[Spring Cloud Contract Documentation]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/deprecated[Accurest Legacy Documentation]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#spring-cloud-contract-stub-runner[Spring Cloud Contract Stub Runner Documentation]
 - https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#stub-runner-for-messaging[Spring Cloud Contract Stub Runner Messaging Documentation]
 - https://gitter.im/spring-cloud/spring-cloud-contract[Spring Cloud Contract Gitter]
- https://github.com/spring-cloud/spring-cloud-contract[Spring Cloud Contract Maven Plugin]
+- https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/[Spring Cloud Contract Maven Plugin]