blog.svenbayer:spring-cloud-contract-swagger

Spring Cloud Contract Swagger

License	The Apache License, Version 2.0
Categories	Swagger Program Interface REST Frameworks
GroupId	blog.svenbayer
ArtifactId	spring-cloud-contract-swagger
Last Version	1.2.0.RELEASE
Release Date	Sep 3, 2018
Type	jar
Description	blog.svenbayer:spring-cloud-contract-swagger Spring Cloud Contract Swagger
Project URL	https://github.com/SvenBayer/spring-cloud-contract-swagger
Project Organization	Spring
Source Code Management	http://github.com/SvenBayer/spring-cloud-contract-swagger/tree/master

Download spring-cloud-contract-swagger

Filename	Size
spring-cloud-contract-swagger-1.2.0.RELEASE.pom
spring-cloud-contract-swagger-1.2.0.RELEASE.jar	40 KB
spring-cloud-contract-swagger-1.2.0.RELEASE-sources.jar	26 KB
spring-cloud-contract-swagger-1.2.0.RELEASE-javadoc.jar	159 KB

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/blog.svenbayer/spring-cloud-contract-swagger/ -->
<dependency>
    <groupId>blog.svenbayer</groupId>
    <artifactId>spring-cloud-contract-swagger</artifactId>
    <version>1.2.0.RELEASE</version>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/blog.svenbayer/spring-cloud-contract-swagger/
implementation 'blog.svenbayer:spring-cloud-contract-swagger:1.2.0.RELEASE'

Gradle Kotlin

// https://jarcasting.com/artifacts/blog.svenbayer/spring-cloud-contract-swagger/
implementation ("blog.svenbayer:spring-cloud-contract-swagger:1.2.0.RELEASE")

Apache Buildr

'blog.svenbayer:spring-cloud-contract-swagger:jar:1.2.0.RELEASE'

Apache Ivy

<dependency org="blog.svenbayer" name="spring-cloud-contract-swagger" rev="1.2.0.RELEASE">
  <artifact name="spring-cloud-contract-swagger" type="jar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='blog.svenbayer', module='spring-cloud-contract-swagger', version='1.2.0.RELEASE')
)

Scala SBT

libraryDependencies += "blog.svenbayer" % "spring-cloud-contract-swagger" % "1.2.0.RELEASE"

Leiningen

[blog.svenbayer/spring-cloud-contract-swagger "1.2.0.RELEASE"]

Dependencies

compile (8)

Group / Artifact	Type	Version
org.springframework : spring-context	jar
org.springframework.cloud : spring-cloud-contract-converters	jar
org.springframework.cloud : spring-cloud-contract-stub-runner	jar
org.springframework.boot : spring-boot-starter-logging	jar
org.codehaus.groovy : groovy	jar
org.codehaus.groovy : groovy-nio	jar
org.springframework.boot : spring-boot-autoconfigure-processor Optional	jar
io.swagger : swagger-parser	jar	1.0.36

test (5)

Group / Artifact	Type	Version
org.spockframework : spock-core	jar	1.0-groovy-2.4
org.springframework.boot : spring-boot-starter-test	jar
info.solidsoft.spock : spock-global-unroll	jar	0.5.1
org.springframework.cloud : spring-cloud-contract-wiremock	jar
org.junit.jupiter : junit-jupiter-api	jar	5.0.2

Project Modules

There are no modules declared in this project.

[Unit Tests [Integration Tests

[SonarQube]

Spring Cloud Contract Swagger

Converts Swagger files to contracts for Spring Cloud Contract

This project enables Spring Cloud Contract to parse Swagger API 2.0 specifications as Spring Cloud Contracts.

Usage

You can check out spring-cloud-contract-swagger-sample for examples.

Producer

To convert a Swagger file to a Spring Cloud Contract and to execute it against a Producer, add the spring-cloud-contract-maven-plugin as plugin and the converter spring-cloud-contract-swagger as plugin-dependency.

Consumer

For the consumer, add as dependencies the spring-cloud-starter-contract-stub-runner and the converter spring-cloud-contract-swagger.

Default Behaviour

Currently, Spring Cloud Contract Swagger generates default values for a Swagger document’s fields.

• Boolean: true
• Number: 1
• Float/Double: 1.1
• String: (the name of the String)

Custom Values

To set your own default values, you can use the x-example field in the parameters and responses section. In the definitions section, you can also use the x-example or the supported example field. You should avoid the default field, since the current Swagger parser (1.0.36) interprets numerical values of default fields as String. Regarding the order, the converter will first evaluate example, then x-example, and then default fields. If it does not find a predefined value, it will go all the way down to the primitive fields. The converter will only use the first response of a Swagger method entry.

Optional Parameters

If you do not want to pass an optional parameter (required: false) in a request, you can add x-ignore: true to this field.

Patterns

Pattern only work for request parameters. Your provided example values will be checked against the pattern.

Custom JSON Body

You can set the request and response body with a json string. For this, you have to place an x-example field next (on the same level) to the schema field. Use single ticks for your json string so you do not have to escape any quotes.

Also, you can reference external json files for the request and response by using the x-ref field. Just place the x-ref field next (on the same level) to the schema field. Use single ticks for the path, relative to the Swagger file.

Recommendation

If you are working in a project that restricts you to define your API with Swagger, this library is for you. Instead of defining your API and Groovy/JSON/YAML contracts, maintaining two separate documents, and risking inconsistency, you can maintain your API specification and contract in one document. This enables you to take at least partly benefit of CDC. The features of this are more restricted then by using proper contracts. However, if possible, you should go the way to define your API with contracts and let the Swagger documentation be generated by your Maven project. See more details at https://github.com/spring-cloud/spring-cloud-contract

If you decide to do contract testing with this project, you might have the choice to move gradually to Spring Cloud Contract with the Swagger Request Validator since Spring Cloud Contract generates WireMock stubs. This would enable you to add Groovy/JSON/YAML contracts and therefore test move scenarios. Thanks to Marcin Grzejszczak for this tip.

Further Information

Read the blog about Consumer Driven Contracts with Swagger for more information.

Versions

Version
1.2.0.RELEASE Sep 3, 2018
1.1.0.RELEASE Aug 4, 2018
1.0.2.RELEASE Jul 24, 2018
1.0.1.RELEASE Jul 17, 2018
1.0.0.RELEASE Jul 16, 2018