tags | projects | |||||
---|---|---|---|---|---|---|
|
|
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
What you’ll build
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.
What you’ll need
Build with Gradle
Build with Gradle
contract-rest-service/build.gradle
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/master/initial/contract-rest-service/build.gradle[]
contract-rest-client/build.gradle
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/master/initial/contract-rest-client/build.gradle[]
Build with Maven
Build with Maven
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/master/initial/contract-rest-service/pom.xml[]
contract-rest-client/pom.xml
link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/master/initial/contract-rest-client/pom.xml[]
Create contract producer service
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[]
Create the contract of the REST service
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. The auto generated test java classes will extend the hello.BaseClass
.
<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>
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.
Check the simple Person query business logic
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[]
Test the contract-rest-service application
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.
Create contract consumer service
With the contract producer service ready, now we need to crate 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[]
Create the contract test
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.
Test the contract-rest-client application
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.
Summary
Congratulations! You’ve just used Spring to make your REST services declare their contract and consumer service be aligned with this contract.
See Also
The following guides may also be helpful: