![[Important]](images/important.png) | Important |
|---|---|
Please read the Groovy docs related to JSON to understand how to properly structure the request / response bodies. |
| Important |
|---|---|
Please read the Groovy docs related to JSON to understand how to properly structure the request / response bodies. |
Let’s try to answer a question what versioning really means. If you’re referring to the API version then there are -different approaches.
I will not try to answer a question which approach is better. Whatever suit your needs and allows you to generate +different approaches.
I will not try to answer a question which approach is better. Whatever suits your needs and allows you to generate business value should be picked.
Let’s assume that you do version your API. In that case you should provide as many contracts as many versions you support. -You can create a subfolder for every version or append it to th contract name - whatever suits you more.
If by versioning you mean the version of the JAR that contains the stubs then there are essentially two main approaches.
Let’s assume that you’re doing Continuous Delivery / Deployment which means that you’re generating a new version of +You can create a subfolder for every version or append it to the contract name - whatever suits you more.
If by versioning you mean the version of the JAR that contains the stubs then there are essentially two main approaches.
Let’s assume that you’re doing Continuous Delivery / Deployment which means that you’re generating a new version of the jar each time you go through the pipeline and that jar can go to production at any time. For example your jar version looks like this (it got built on the 20.10.2016 at 20:15:21) :
1.0.0.20161020-201521-RELEASE
In that case your generated stub jar will look like this.
1.0.0.20161020-201521-RELEASE-stubs.jar
In this case you should inside your application.yml or @AutoConfigureStubRunner when referencing stubs provide the
latest version of the stubs. You can do that by passing the + sign. Example
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"})If the versioning however is fixed (e.g. 1.0.4.RELEASE or 2.1.1) then you have to set the concrete value of the jar
@@ -80,7 +80,7 @@ version. Example for 2.1.1.
@AutoConfigureStubRun once you reach production deployment then you can run tests in one case with dev stubs and one with prod stubs.Example of tests using development version of stubs
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"})Example of tests using production version of stubs
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:prod-stubs:8080"})You can pass those values also via properties from your deployment pipeline.
Another way of storing contracts other than having them with the producer is keeping them in a common place. It can be related to security issues where the consumers can’t clone the producer’s code. Also if you keep contracts in a single place then you, as a producer, will know how many consumers you have and which -consumer will you break with your local changes.
Let’s assume that we have a producer with coordinates com.example:server and 3 consumers: client1,
+consumer you will break with your local changes.
Let’s assume that we have a producer with coordinates com.example:server and 3 consumers: client1,
client2, client3. Then in the repository with common contracts you would have the following setup
(which you can checkout here):
├── com │ └── example @@ -97,7 +97,7 @@ consumer will you break with your local changes.As you can see the under the slash-delimited groupid
/artifact id folder (com/example/server) you have + └── contracts.xmlAs you can see under the slash-delimited groupid
/artifact id folder (com/example/server) you have expectations of the 3 consumers (client1,client2andclient3). Expectations are the standard Groovy DSL contract files as described throughout this documentation. This repository has to produce a JAR file that maps one to one to the contents of the repo.Example of a
pom.xmlinside theserverfolder.<?xml version="1.0" encoding="UTF-8"?> @@ -473,12 +473,12 @@ to find stub definitions and contracts. E.g. forcom.examp to store and share Pact definitions. Starting from Spring Cloud Contract 2.0.0 one can fetch Pact files from the Pact Broker to generate tests and stubs.As a prerequisite the Pact Converter and Pact Stub Downloader -are required. You have to add it via the
spring-cloud-contract-pactdependency. +are required. You have to add them via thespring-cloud-contract-pactdependency. You can read more about it in the Section 10.1.1, “Pact Converter” section.
Important Pact follows the Consumer Contract convention. That means that the Consumer creates the Pact definitions first, then shares the files with the Producer. Those expectations are generated -from the Consumer’s code and can break the Producer if the expectation -is not met.
The consumer uses Pact framework to generate Pact files. The +from the Consumer’s code and can break the Producer if the expectations +are not met.
The consumer uses Pact framework to generate Pact files. The Pact files are sent to the Pact Broker. An example of such setup can be found here.
For the producer, to use the Pact files from the Pact Broker, we can reuse the same mechanism we use for external contracts. We route Spring Cloud Contract diff --git a/single/spring-cloud-contract.html b/single/spring-cloud-contract.html index 071fa52f64..0564fd3032 100644 --- a/single/spring-cloud-contract.html +++ b/single/spring-cloud-contract.html @@ -846,9 +846,9 @@ for time and UUID are simplified and most likely invalid but we want to keep thi } }
Important Please read the Groovy docs related to JSON to understand how to properly structure the request / response bodies.
Let’s try to answer a question what versioning really means. If you’re referring to the API version then there are -different approaches.
- use Hypermedia, links and do not version your API by any means
- pass versions through headers / urls
I will not try to answer a question which approach is better. Whatever suit your needs and allows you to generate +different approaches.
- use Hypermedia, links and do not version your API by any means
- pass versions through headers / urls
I will not try to answer a question which approach is better. Whatever suits your needs and allows you to generate business value should be picked.
Let’s assume that you do version your API. In that case you should provide as many contracts as many versions you support. -You can create a subfolder for every version or append it to th contract name - whatever suits you more.
If by versioning you mean the version of the JAR that contains the stubs then there are essentially two main approaches.
Let’s assume that you’re doing Continuous Delivery / Deployment which means that you’re generating a new version of +You can create a subfolder for every version or append it to the contract name - whatever suits you more.
If by versioning you mean the version of the JAR that contains the stubs then there are essentially two main approaches.
Let’s assume that you’re doing Continuous Delivery / Deployment which means that you’re generating a new version of the jar each time you go through the pipeline and that jar can go to production at any time. For example your jar version looks like this (it got built on the 20.10.2016 at 20:15:21) :
1.0.0.20161020-201521-RELEASEIn that case your generated stub jar will look like this.
1.0.0.20161020-201521-RELEASE-stubs.jarIn this case you should inside your
application.ymlor@AutoConfigureStubRunnerwhen referencing stubs provide the latest version of the stubs. You can do that by passing the+sign. Example@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"})If the versioning however is fixed (e.g.
1.0.4.RELEASEor2.1.1) then you have to set the concrete value of the jar @@ -857,7 +857,7 @@ version. Example for 2.1.1.@AutoConfigureStubRun once you reach production deployment then you can run tests in one case with dev stubs and one with prod stubs.Example of tests using development version of stubs
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"})Example of tests using production version of stubs
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:prod-stubs:8080"})You can pass those values also via properties from your deployment pipeline.
Another way of storing contracts other than having them with the producer is keeping them in a common place. It can be related to security issues where the consumers can’t clone the producer’s code. Also if you keep contracts in a single place then you, as a producer, will know how many consumers you have and which -consumer will you break with your local changes.
Let’s assume that we have a producer with coordinates
com.example:serverand 3 consumers:client1, +consumer you will break with your local changes.Let’s assume that we have a producer with coordinates
com.example:serverand 3 consumers:client1,client2,client3. Then in the repository with common contracts you would have the following setup (which you can checkout here):├── com │ └── example @@ -874,7 +874,7 @@ consumer will you break with your local changes.As you can see the under the slash-delimited groupid
/artifact id folder (com/example/server) you have + └── contracts.xmlAs you can see under the slash-delimited groupid
/artifact id folder (com/example/server) you have expectations of the 3 consumers (client1,client2andclient3). Expectations are the standard Groovy DSL contract files as described throughout this documentation. This repository has to produce a JAR file that maps one to one to the contents of the repo.Example of a
pom.xmlinside theserverfolder.<?xml version="1.0" encoding="UTF-8"?> @@ -1250,12 +1250,12 @@ to find stub definitions and contracts. E.g. forcom.examp to store and share Pact definitions. Starting from Spring Cloud Contract 2.0.0 one can fetch Pact files from the Pact Broker to generate tests and stubs.As a prerequisite the Pact Converter and Pact Stub Downloader -are required. You have to add it via the
spring-cloud-contract-pactdependency. +are required. You have to add them via thespring-cloud-contract-pactdependency. You can read more about it in the Section 10.1.1, “Pact Converter” section.
Important Pact follows the Consumer Contract convention. That means that the Consumer creates the Pact definitions first, then shares the files with the Producer. Those expectations are generated -from the Consumer’s code and can break the Producer if the expectation -is not met.
The consumer uses Pact framework to generate Pact files. The +from the Consumer’s code and can break the Producer if the expectations +are not met.
The consumer uses Pact framework to generate Pact files. The Pact files are sent to the Pact Broker. An example of such setup can be found here.
For the producer, to use the Pact files from the Pact Broker, we can reuse the same mechanism we use for external contracts. We route Spring Cloud Contract diff --git a/spring-cloud-contract.xml b/spring-cloud-contract.xml index d9a471d41e..19b137e773 100644 --- a/spring-cloud-contract.xml +++ b/spring-cloud-contract.xml @@ -1473,10 +1473,10 @@ different approaches.
pass versions through headers / urls -I will not try to answer a question which approach is better. Whatever suit your needs and allows you to generate + I will not try to answer a question which approach is better. Whatever suits your needs and allows you to generate business value should be picked. Let’s assume that you do version your API. In that case you should provide as many contracts as many versions you support. -You can create a subfolder for every version or append it to th contract name - whatever suits you more. +You can create a subfolder for every version or append it to the contract name - whatever suits you more.JAR versioning @@ -1511,7 +1511,7 @@ version. Example for 2.1.1.Another way of storing contracts other than having them with the producer is keeping them in a common place. It can be related to security issues where the consumers can’t clone the producer’s code. Also if you keep contracts in a single place then you, as a producer, will know how many consumers you have and which -consumer will you break with your local changes. +consumer you will break with your local changes.Repo structure Let’s assume that we have a producer with coordinates └── src └── assembly └── contracts.xml -com.example:server and 3 consumers:client1 , @@ -1533,7 +1533,7 @@ consumer will you break with your local changes.As you can see the under the slash-delimited groupid / artifact id folder (com/example/server ) you have +As you can see under the slash-delimited groupid @@ -2090,14 +2090,14 @@ to store and share Pact definitions. Starting from Spring Cloud Contract 2.0.0 one can fetch Pact files from the Pact Broker to generate tests and stubs./ artifact id folder (com/example/server ) you have expectations of the 3 consumers (client1 ,client2 andclient3 ). Expectations are the standard Groovy DSL contract files as described throughout this documentation. This repository has to produce a JAR file that maps one to one to the contents of the repo.As a prerequisite the Pact Converter and Pact Stub Downloader -are required. You have to add it via the spring-cloud-contract-pact dependency. +are required. You have to add them via thespring-cloud-contract-pact dependency. You can read more about it in thesection. Pact follows the Consumer Contract convention. That means that the Consumer creates the Pact definitions first, then shares the files with the Producer. Those expectations are generated -from the Consumer’s code and can break the Producer if the expectation -is not met. +from the Consumer’s code and can break the Producer if the expectations +are not met.Pact Consumer