SCC Verifier MultiApi Converter allows us to use Spring Cloud Contract to generate contracts from an OpenApi yaml or AsyncApi yaml document
MPL-2.0 License
SCC Verifier MultiApi Converter allows us to use Spring Cloud Contract to generate contracts from an OpenApi yaml document or an AsyncApi document. This plugin will detect automatically what contract needs to be generated
Here is the documentation for these technologies:
In order to get this plugin working, you need the following things installed in your computer:
After you have these installed, you need to add the Spring Cloud Contract Maven Plugin in your pom.xml file and extend it with this Converter as a Dependency. Here is an easy example of a basic configuration:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>3.0.0</version>
<extensions>true</extensions>
<configuration>
<packageWithBaseClasses>com.sngular.challenge.gameserver.baseclasses</packageWithBaseClasses>
<contractsDirectory>${project.basedir}/src/main/resources/api</contractsDirectory>
</configuration>
<dependencies>
<dependency>
<groupId>com.sngular</groupId>
<artifactId>scc-multiapi-converter</artifactId>
<version>3.4.1</version>
<scope>compile</scope>
</dependency>
</dependencies>
</plugin>
Inside the configuration tag, you must declare the contractsDirectory tag. In this tag you must specify the directory that contains the OpenApi/AsyncApi Yamls.
Also, we recommend specifying the baseClassForTests tag. This tag indicates the base class from which the autogenerated test will be extended. This class must be a test class of the producer part in which only a call to the producer method will be made, which is necessary for the test of the producer of the autogenerated class.
Once you specify this in your pom.xml you must use the command: mvn clean install. This will generate the stubs necessary for the contract testing generation under the stubs folder.
It will also generate the ContractVerifierTest class for the producer and consumer tests for your Messaging Api and your Rest Api, in addition to the corresponding yml files with the contracts of both, inside target in the package where your baseClassForTests is located. If you want to change where your contracts will be located you must use the basePackageForTests tag in the pom.xml.
If you need more control over the settings of your project, you can use all the Configuration Options that Spring Cloud Contract Maven Plugin has. These configuration options can be checked in the official documentation webpage under 4.2.7 Section: Spring Cloud Contract Verifier Setup.
This plugin supports most of the OpenApi/Swagger and AsyncApi, but there are a couple of things that must be noted:
This is an easy example of a small YAML for OpenApi that will work with our plugin:
---
openapi: "3.0.0"
info:
version: 1.0.0
title: Sngular Challenge Game Server
description: Test File for SCC MultiApi Plugin.
contact:
name: Sngular
url: sngular.com
email: [email protected]
license:
name: MPL 2.0
servers:
- url: http://localhost:8080/v1
paths:
/games:
summary: Hola
get:
summary: List all available games
description: Test File for SCC MultiApi Plugin.
tags:
- games
operationId: listGames
responses:
'200':
description: A paged array of games
content:
application/json:
schema:
$ref: "#/components/schemas/Game"
components:
schemas:
Game:
type: object
properties:
player:
$ref: "#/components/schemas/Player"
Player:
type: object
properties:
name:
$ref: "#/components/schemas/Name"
Name:
type: object
properties:
firstname:
type: string
example: John
lastname:
type: string
example: Doe
tags:
- name: games
description: Test description for SCC MultiApi Plugin.
And here, there is an example of a YAML file for the AsyncApi side:
asyncapi: "2.3.0"
info:
title: Order Service
version: 1.0.0
description: Order management Service
contact:
name: Sngular
url: http://www.asyncapi.org/support
email: [email protected]
license:
name: MPL 2.0
channels:
orderCreated:
publish:
operationId: "publishOperation"
message:
$ref: '#/components/messages/OrderCreated'
description: Operation that will produce an OrderCreated object
createOrder:
subscribe:
operationId: "subscribeOperation"
message:
$ref: '#/components/messages/CreateOrder'
description: Operation that will consume an CreateOrder object
components:
messages:
OrderCreated:
payload:
$ref: '#/components/schemas/Order'
CreateOrder:
payload:
$ref: '#/components/schemas/Order'
schemas:
Order:
type: object
properties:
tableNumber:
type: integer
format: int32
example: 1
clientRef:
type: integer
format: int32
example: 432
Currently, this plugin has some limitations that will be addressed in the future. In order to make it work, we must follow some rules:
OpenApi implementation:
Async Api implementation: