/gs-contract-rest

Consumer Driven Contracts :: Learn how to with contract stubs and consuming that contract from another Spring application

Primary LanguageJava

Table of Contents

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[role=include]

contract-rest-client/build.gradle

link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/master/initial/contract-rest-client/build.gradle[role=include]

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[role=include]

contract-rest-client/pom.xml

link:https://raw.githubusercontent.com/spring-guides/gs-contract-rest/master/initial/contract-rest-client/pom.xml[role=include]

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[role=include]

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[role=include]

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[role=include]

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[role=include]

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[role=include]

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[role=include]

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[role=include]

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[role=include]

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: