This guide walks you through the process of creating a Spring REST application with its contract stubs and consuming the contract within an other Spring application. Spring Cloud Contract Project
You’ll setup two micro services one providing its contract, and the other one consuming this contract to make sure that the integration to the contract provider service is aligned with the specifications. If in the future, the contract of the producer service changes, then the consumer service’s tests fail catching the potential incompatibility.
contract-rest-service/build.gradle
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/main/initial/contract-rest-service/build.gradle[]contract-rest-client/build.gradle
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/main/initial/contract-rest-client/build.gradle[]To get you started quickly, here are the complete configurations for the server and client applications:
contract-rest-service/pom.xml
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/main/initial/contract-rest-service/pom.xml[]contract-rest-client/pom.xml
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/main/initial/contract-rest-client/pom.xml[]You’ll first need to create the service which produces the contract. This is a regular Spring Boot application providing a very simple REST service. The rest service simply returns a Person object in JSON.
contract-rest-service/src/main/java/hello/ContractRestServiceApplication.java
link:complete/contract-rest-service/src/main/java/hello/ContractRestServiceApplication.java[]The contract of the REST service can be defined as a .groovy script. This contract specifies that if there is a GET request to url /person/1, sample data id=1, name=foo and surname=bee representing a Person entity will be returned in the response body of content-type application/json .
contract-rest-service/src/test/resources/contracts/hello/find_person_by_id.groovy
link:complete/contract-rest-service/src/test/resources/contracts/hello/find_person_by_id.groovy[]At the test phase, automatic test classes will be created for the contract specified in the groovy file. This is done by the build plugin org.springframework.cloud:spring-cloud-contract-gradle-plugin in Gradle or org.springframework.cloud:spring-cloud-contract-maven-plugin in Maven respectively. The auto generated test java classes will extend the hello.BaseClass.
To include the plugin in Maven, you need to add the following:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>${spring-cloud-contract.version}</version>
<extensions>true</extensions>
<configuration>
<baseClassForTests>hello.BaseClass</baseClassForTests>
</configuration>
</plugin>For running the tests, you also need to include the org.springframework.cloud:spring-cloud-starter-contract-verifier dependency in the test scope.
Finally, create the base-class for testing:
contract-rest-service/src/test/java/hello/BaseClass.java
link:complete/contract-rest-service/src/test/java/hello/BaseClass.java[]At this step, when the tests are executed, test results should be GREEN indicating that the REST controller is aligned with the contract and you have a fully functioning service.
Model class Person.java
contract-rest-service/src/main/java/hello/Person.java
link:complete/contract-rest-service/src/main/java/hello/Person.java[]Service bean PersonService.java which just populates a few Person entity in memory and returns the one when asked.
contract-rest-service/src/main/java/hello/PersonService.java
link:complete/contract-rest-service/src/main/java/hello/PersonService.java[]RestController bean PersonRestController.java which calls PersonService bean when a REST request is received for a person with the id.
contract-rest-service/src/main/java/hello/PersonRestController.java
link:complete/contract-rest-service/src/main/java/hello/PersonRestController.java[]Run the ContractRestServiceApplication.java class as a Java Application or Spring Boot Application. The service should start at port 8000.
Visit the service in the browser http://localhost:8000/person/1, http://localhost:8000/person/2, etc.
With the contract producer service ready, now we need to create the client application which consumes the contract provided. This is a regular Spring Boot application providing a very simple REST service. The rest service simply returns a message with the queried Person’s name, e.g. Hello Anna.
contract-rest-client/src/main/java/hello/ContractRestClientApplication.java
link:complete/contract-rest-client/src/main/java/hello/ContractRestClientApplication.java[]The contract provided by the producer should be consumed as a simple Spring test.
contract-rest-client/src/test/java/hello/ContractRestClientApplicationTest.java
link:complete/contract-rest-client/src/test/java/hello/ContractRestClientApplicationTest.java[]This test class will load the stubs of the contract producer service and make sure that the integration to the service is aligned with the contract.
In case the communication is faulty between the consumer service’s test and the producer’s contract, tests will fail and the problem will need to be fixed before making a new change on production.
Run the ContractRestClientApplication.java class as a Java Application or Spring Boot Application. The service should start at port 9000.
Visit the service in the browser http://localhost:9000/message/1, http://localhost:9000/message/2, etc.
Congratulations! You’ve just used Spring to make your REST services declare their contract and consumer service be aligned with this contract.
The following guides may also be helpful: