From 4fbd4daa4f2d322d53b1933238370ef0d0a37a64 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Tue, 26 Jul 2016 11:45:55 +0200 Subject: [PATCH] Updated docs --- README.adoc | 81 ++++++++++++++----- .../main/asciidoc/verifier/introduction.adoc | 9 ++- 2 files changed, 70 insertions(+), 20 deletions(-) diff --git a/README.adoc b/README.adoc index fe981a06e9..c3545da7c0 100644 --- a/README.adoc +++ b/README.adoc @@ -311,37 +311,80 @@ As consumers we need to define what exactly we want to achieve. We need to formu package contracts org.springframework.cloud.contract.spec.Contract.make { - request { - method 'PUT' - url '/fraudcheck' - body(""" - { - "clientId":"${value(consumer(regex('[0-9]{10}')))}", - "loanAmount":99999} - """ - ) - headers { + request { // (1) + method 'PUT' // (2) + url '/fraudcheck' // (3) + body([ // (4) + clientId: value(consumer(regex('[0-9]{10}'))), + loanAmount: 99999 + ]) + headers { // (5) header('Content-Type', 'application/vnd.fraud.v1+json') } } - response { - status 200 - body( """{ - "fraudCheckStatus": "FRAUD", - "rejectionReason": "Amount too high" - }""") - headers { + response { // (6) + status 200 // (7) + body([ // (8) + fraudCheckStatus: "FRAUD", + rejectionReason: "Amount too high" + ]) + headers { // (9) header('Content-Type': value( producer(regex('application/vnd.fraud.v1.json.*')), consumer('application/vnd.fraud.v1+json')) ) } } - } + +/* +Since we don't want to force on the user to hardcode values of fields that are dynamic +(timestamps, database ids etc.), one can provide parametrize those entries by using the +`value(consumer(...), producer(...))` method. That way what's present in the `consumer` +section will end up in the produced stub. What's there in the `producer` will end up in the +autogenerated test. If you provide only the regular expression side without the concrete +value then Spring Cloud Contract will generate one for you. + +From the Consumer perspective, when shooting a request in the integration test: + +(1) - If the consumer sends a request +(2) - With the "PUT" method +(3) - to the URL "/fraudcheck" +(4) - with the JSON body that + * has a field `clientId` that matches a regular expression `[0-9]{10}` + * has a field `loanAmount` that is equal to `99999` +(5) - with header `Content-Type` equal to `application/vnd.fraud.v1+json` +(6) - then the response will be sent with +(7) - status equal `200` +(8) - and JSON body equal to + { "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" } +(9) - with header `Content-Type` equal to `application/vnd.fraud.v1+json` + +From the Producer perspective, in the autogenerated producer-side test: + +(1) - A request will be sent to the producer +(2) - With the "PUT" method +(3) - to the URL "/fraudcheck" +(4) - with the JSON body that + * has a field `clientId` that will have a generated value that matches a regular expression `[0-9]{10}` + * has a field `loanAmount` that is equal to `99999` +(5) - with header `Content-Type` equal to `application/vnd.fraud.v1+json` +(6) - then the test will assert if the response has been sent with +(7) - status equal `200` +(8) - and JSON body equal to + { "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" } +(9) - with header `Content-Type` matching `application/vnd.fraud.v1+json.*` + */ ---- -The Contract is written using a statically typed Groovy DSL. You might be wondering what are those `${value(consumer(...), producer(...))}` parts. So the `${}` is a String interpolation in Groovy. You can resolve a variable inside a String. In other words `"concat ${foo} and ${bar}"` is the same as `"concat " + foo + " and " + bar`. The `value(consumer(...), producer(...))` allows you to define parts of a JSON which are dynamic. In case of an identifier or a timestamp you don't want to hardcode a value. You want to allow some different ranges of values. That's why for the consumer side you can set regular expressions matching those values. You can provide the body either by means of String with interpolations or with a map notation. https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_contract_dsl[Consult the docs for more information.] +The Contract is written using a statically typed Groovy DSL. You might be wondering what are those +`value(client(...), server(...))` parts. By using this notation Spring Cloud Contract allows you to +define parts of a JSON / URL / etc. which are dynamic. In case of an identifier or a timestamp you +don't want to hardcode a value. You want to allow some different ranges of values. That's why for +the consumer side you can set regular expressions matching those values. You can provide the body +either by means of a map notation or String with interpolations. +https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_contract_dsl[Consult the docs +for more information.] We highly recommend using the map notation! The aforementioned contract is an agreement between two sides that: diff --git a/docs/src/main/asciidoc/verifier/introduction.adoc b/docs/src/main/asciidoc/verifier/introduction.adoc index 36ceb92bba..8f8400d122 100644 --- a/docs/src/main/asciidoc/verifier/introduction.adoc +++ b/docs/src/main/asciidoc/verifier/introduction.adoc @@ -160,7 +160,14 @@ As consumers we need to define what exactly we want to achieve. We need to formu include::{introduction_url}/samples/standalone/http-server/src/test/resources/contracts/shouldMarkClientAsFraud.groovy[] ---- -The Contract is written using a statically typed Groovy DSL. You might be wondering what are those `${value(consumer(...), producer(...))}` parts. So the `${}` is a String interpolation in Groovy. You can resolve a variable inside a String. In other words `"concat ${foo} and ${bar}"` is the same as `"concat " + foo + " and " + bar`. The `value(consumer(...), producer(...))` allows you to define parts of a JSON which are dynamic. In case of an identifier or a timestamp you don't want to hardcode a value. You want to allow some different ranges of values. That's why for the consumer side you can set regular expressions matching those values. You can provide the body either by means of String with interpolations or with a map notation. https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_contract_dsl[Consult the docs for more information.] +The Contract is written using a statically typed Groovy DSL. You might be wondering what are those +`value(client(...), server(...))` parts. By using this notation Spring Cloud Contract allows you to +define parts of a JSON / URL / etc. which are dynamic. In case of an identifier or a timestamp you +don't want to hardcode a value. You want to allow some different ranges of values. That's why for +the consumer side you can set regular expressions matching those values. You can provide the body +either by means of a map notation or String with interpolations. +https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_contract_dsl[Consult the docs +for more information.] We highly recommend using the map notation! The aforementioned contract is an agreement between two sides that: