SpringCloud/spring-cloud-contract
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

WIP

Browse Source
This commit is contained in:
Marcin Grzejszczak
2019-07-11 17:00:25 +02:00
parent 82be516441
commit 554d59bf91
20 changed files with 1104 additions and 1117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

420
README.adoc
View File

@@ -8,8 +8,24 @@ Edit the files in the src/main/asciidoc/ directory instead.
image::https://badges.gitter.im/Join%20Chat.svg[Gitter, link="https://gitter.im/spring-cloud/spring-cloud-contract?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
image::https://codecov.io/gh/spring-cloud/spring-cloud-contract/branch/{branch}/graph/badge.svg["codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-contract"]
image::https://circleci.com/gh/spring-cloud/spring-cloud-contract.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-contract"]
:introduction_url: ../../../..
:verifier_core_path: {introduction_url}/spring-cloud-contract-verifier
:branch: master
:core_path: ../../..
:plugins_path: ../../../spring-cloud-contract-tools
:converters_path: {plugins_path}/spring-cloud-contract-converters
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:contract_spec_path: {core_path}/specs/spring-cloud-contract-spec-java
:contract_spec_tests_path: {core_path}/specs/spring-cloud-contract-spec
:samples_path: {core_path}/samples
:verifier_core_path: {verifier_root_path}
:stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner
:standalone_samples_path: {samples_path}/standalone/dsl
:standalone_messaging_samples_path: {samples_path}/standalone/messaging
:standalone_pact_path: {samples_path}/standalone/pact
:standalone_restdocs_path: {samples_path}/standalone/restdocs
:tests_path: {core_path}/tests
:samples_branch: 2.2.x
:samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/{samples_branch}
:introduction_url: ${core_path}/../../
== Spring Cloud Contract
@@ -27,23 +43,9 @@ https://cloud-samples.spring.io/spring-cloud-contract-samples/workshops.html[thi
=== Spring Cloud Contract Verifier
== Spring Cloud Contract Verifier Introduction
== Spring Cloud Contract Introduction
Spring Cloud Contract Verifier enables Consumer Driven Contract (CDC) development of
JVM-based applications. It moves TDD to the level of software architecture.
Spring Cloud Contract Verifier ships with _Contract Definition Language_ (CDL). Contract
definitions are used to produce the following resources:
* JSON stub definitions to be used by WireMock when doing integration testing on the
client code (_client tests_). Test code must still be written by hand, and test data is
produced by Spring Cloud Contract Verifier.
* Messaging routes, if you're using a messaging service. We integrate with Spring
Integration, Spring Cloud Stream, Spring AMQP, and Apache Camel. You can also set your
own integrations.
* Acceptance tests (in JUnit 4, JUnit 5 or Spock) are used to verify if server-side implementation
of the API is compliant with the contract (__server tests__). A full test is generated by
Spring Cloud Contract Verifier.
Spring Cloud Contract moves TDD to the level of software architecture. It allows to perform consumer, consumer-driven and producer-driven contract testing.
=== History
@@ -71,6 +73,7 @@ Both have their advantages but also a lot of disadvantages.
*Deploy all microservices and perform end to end tests*
Advantages:
- Simulates production.
@@ -99,29 +102,30 @@ Disadvantages:
reality.
- You can go to production with passing tests and failing production.
To solve the aforementioned issues, Spring Cloud Contract Verifier with Stub Runner was
created. The main idea is to give you very fast feedback, without the need to set up the
To solve the aforementioned issues, Spring Cloud Contract was created. The main idea is to give you very fast feedback, without the need to set up the
whole world of microservices. If you work on stubs, then the only applications you need
are those that your application directly uses.
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/docs/src/main/asciidoc/images/Stubs2.png[Stubbed Services]
Spring Cloud Contract Verifier gives you the certainty that the stubs that you use were
Spring Cloud Contract gives you the certainty that the stubs that you use were
created by the service that you're calling. Also, if you can use them, it means that they
were tested against the producer's side. In short, you can trust those stubs.
=== Purposes
The main purposes of Spring Cloud Contract Verifier with Stub Runner are:
The main purposes of Spring Cloud Contract are:
- To ensure that WireMock/Messaging stubs (used when developing the client) do exactly
- To ensure that Http / Messaging stubs (used when developing the client) do exactly
what the actual server-side implementation does.
- To promote ATDD method and Microservices architectural style.
- To promote ATDD (acceptance test driven developement) method and Microservices architectural style.
- To provide a way to publish changes in contracts that are immediately visible on both
sides.
- To generate boilerplate test code to be used on the server side.
IMPORTANT: Spring Cloud Contract Verifier's purpose is NOT to start writing business
By default Spring Cloud Contract integrates with http://wiremock.org[Wiremock] as the HTTP server stub.
IMPORTANT: Spring Cloud Contract's purpose is NOT to start writing business
features in the contracts. Assume that we have a business use case of fraud check. If a
user can be a fraud for 100 different reasons, we would assume that you would create 2
contracts, one for the positive case and one for the negative case. Contract tests are
@@ -129,7 +133,7 @@ used to test contracts between applications and not to simulate full behavior.
=== How It Works
This section explores how Spring Cloud Contract Verifier with Stub Runner works.
This section explores how Spring Cloud Contract.
[[spring-cloud-contract-verifier-intro-three-second-tour]]
==== A Three-second Tour
@@ -142,10 +146,28 @@ This very brief tour walks through using Spring Cloud Contract:
You can find a somewhat longer tour
<<spring-cloud-contract-verifier-intro-three-minute-tour,here>>.
[plantuml, three-second, png]
----
"API Producer"->"API Producer": add Spring Cloud \nContract (SCC) plugin
"API Producer"->"API Producer": add SCC Verifier dependency
"API Producer"->"API Producer": define contracts
"API Producer"->"Build": run build
"Build"->"SCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar)
"Build"->"Nexus / Artifactory": upload contracts \nand stubs and the project arifact
"Build"->"API Producer": Build successful
"API Consumer"->"API Consumer": add SCC Stub Runner \ndependency
"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test
"SCC Stub Runner"->"Nexus / Artifactory": test asks for [API Producer] stubs
"Nexus / Artifactory"->"SCC Stub Runner": fetch the [API Producer] stubs
"SCC Stub Runner"->"SCC Stub Runner": run in memory\n HTTP server stubs
"API Consumer"->"SCC Stub Runner": send a request \nto the HTTP server stub
"SCC Stub Runner"->"API Consumer": communication is correct
----
[[spring-cloud-contract-verifier-intro-three-second-tour-producer]]
===== On the Producer Side
To start working with Spring Cloud Contract, add files with `REST/` messaging contracts
To start working with Spring Cloud Contract, add files with `REST`/messaging contracts
expressed in either Groovy DSL or YAML to the contracts directory, which is set by the
`contractsDslDir` property. By default, it is `$rootDir/src/test/resources/contracts`.
@@ -154,7 +176,7 @@ shown in the following example:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0]
----
The following listing shows how to add the plugin, which should go in the build/plugins
@@ -199,7 +221,7 @@ following example:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0]
----
You can get the Producer-side stubs installed in your Maven repository in either of two
@@ -221,9 +243,7 @@ Stub Runner` properties, as shown in the following example:
+
[source,yaml,indent=0]
----
stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: https://repo.spring.io/libs-snapshot
Unresolved directive in _verifier_how_it_works.adoc - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/master/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
----
Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation,
@@ -265,9 +285,11 @@ expressed in either Groovy DSL or YAML to the contracts directory, which is set
For the HTTP stubs, a contract defines what kind of response should be returned for a
given request (taking into account the HTTP methods, URLs, headers, status codes, and so
on). The following example shows how an HTTP stub contract in Groovy DSL:
on). The following example shows how an HTTP stub contract:
[source,groovy,indent=0]
====
[source,groovy,indent=0,role="primary"]
.groovy
----
package contracts
@@ -296,9 +318,8 @@ org.springframework.cloud.contract.spec.Contract.make {
}
----
The same contract expressed in YAML would look like the following example:
[source,yaml,indent=0]
[source,yaml,indent=0,role="secondary"]
.yaml
----
request:
method: PUT
@@ -321,6 +342,7 @@ response:
headers:
Content-Type: application/json;charset=UTF-8
----
====
In the case of messaging, you can define:
@@ -329,26 +351,29 @@ was sent, the message body, and the header).
* The methods that should be called after the message is received.
* The methods that, when called, should trigger a message.
The following example shows a Camel messaging contract expressed in Groovy DSL:
The following example shows a Camel messaging contract:
[source,groovy]
====
[source,groovy,indent=0,role="primary"]
.groovy
----
Unresolved directive in verifier_introduction.adoc - include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_dsl]
Unresolved directive in _verifier_how_it_works.adoc - include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_dsl]
----
The following example shows the same contract expressed in YAML:
[source,yaml,indent=0,role="secondary"]
.yaml
----
Unresolved directive in _verifier_how_it_works.adoc - include::{verifier_core_path}/src/test/resources/yml/contract_message_scenario3.yml[indent=0]
----
====
[source,yml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{verifier_core_path}/src/test/resources/yml/contract_message_scenario3.yml[indent=0]
----
Then you can add Spring Cloud Contract Verifier dependency and plugin to your build file,
as shown in the following example:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0]
----
The following listing shows how to add the plugin, which should go in the build/plugins
@@ -404,7 +429,7 @@ In order to use `WebTestClient` set `testMode` to `WEBTESTCLIENT`.
Here is an example of a test generated in `WEBTESTCLIENT` test mode:
[source,java,indent=0]
[source,java,indent=0]
----
@Test
public void validate_shouldRejectABeerIfTooYoung() throws Exception {
@@ -434,7 +459,7 @@ order number followed by an underscore at the beginning of the contract file nam
The following example shows an auto-generated test in Spock for a messaging stub contract:
[source,groovy,indent=0]
[source,groovy,indent=0]
----
given:
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
@@ -503,7 +528,7 @@ To get started, add the dependency to `Spring Cloud Contract Stub Runner`:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0]
----
You can get the Producer-side stubs installed in your Maven repository in either of two
@@ -525,9 +550,7 @@ Runner` properties, as shown in the following example:
+
[source,yaml,indent=0]
----
stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: https://repo.spring.io/libs-snapshot
Unresolved directive in _verifier_how_it_works.adoc - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/master/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
----
Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation,
@@ -570,17 +593,19 @@ Assume that you want to send a request containing the ID of a client company and
amount it wants to borrow from us. You also want to send it to the /fraudcheck url via
the PUT method.
.Groovy DSL
[source,groovy,indent=0]
====
[source,groovy,indent=0,role="primary"]
.groovy
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[]
----
.YAML
[source,yml,indent=0]
[source,yaml,indent=0,role="secondary"]
.yaml
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/yml/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.yml[]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/yml/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.yml[]
----
====
==== Client Side
@@ -592,14 +617,14 @@ At some point in time, you need to send a request to the Fraud Detection service
[source,groovy,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/main/java/com/example/loan/LoanApplicationService.java[tags=client_call_server,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/main/java/com/example/loan/LoanApplicationService.java[tags=client_call_server,indent=0]
----
Annotate your test class with `@AutoConfigureStubRunner`. In the annotation provide the group id and artifact id for the Stub Runner to download stubs of your collaborators.
[source,groovy,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=autoconfigure_stubrunner,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=autoconfigure_stubrunner,indent=0]
----
After that, during the tests, Spring Cloud Contract automatically finds the stubs
@@ -671,13 +696,13 @@ following section to your build:
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
.Maven
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=repos,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=repos,indent=0]
----
[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"]
.Gradle
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/build.gradle[tags=deps_repos,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/build.gradle[tags=deps_repos,indent=0]
----
==== Consumer side (Loan Issuance)
@@ -701,7 +726,7 @@ As a developer of the Loan Issuance service (a consumer of the Fraud Detection s
[source,groovy,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=client_tdd,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=client_tdd,indent=0]
----
Assume that you have written a test of your new feature. If a loan application for a big
@@ -715,7 +740,7 @@ client wants to borrow. You want to send it to the `/fraudcheck` url via the `PU
[source,groovy,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/main/java/com/example/loan/LoanApplicationService.java[tags=client_call_server,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/main/java/com/example/loan/LoanApplicationService.java[tags=client_call_server,indent=0]
----
For simplicity, the port of the Fraud Detection service is set to `8080`, and the
@@ -742,17 +767,19 @@ your expectations. To do so, write the following contract:
IMPORTANT: Place the contract under `src/test/resources/contracts/fraud` folder. The `fraud` folder
is important because the producer's test base class name references that folder.
.Groovy DSL
[source,groovy,indent=0]
====
[source,groovy,indent=0,role="primary"]
.groovy
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[]
----
.YAML
[source,yml,indent=0]
[source,yaml,indent=0,role="secondary"]
.yaml
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/yml/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.yml[]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/yml/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.yml[]
----
====
The YML contract is quite straight-forward. However when you take a look at the Contract
written using a statically typed Groovy DSL - you might wonder what the
@@ -790,14 +817,14 @@ First, add the `Spring Cloud Contract` BOM.
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_bom,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_bom,indent=0]
----
Next, add the `Spring Cloud Contract Verifier` Maven plugin
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0]
----
Since the plugin was added, you get the `Spring Cloud Contract Verifier` features which,
@@ -853,14 +880,14 @@ Add the `Spring Cloud Contract` BOM:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=contract_bom,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=contract_bom,indent=0]
----
Add the dependency to `Spring Cloud Contract Stub Runner`:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0]
----
Annotate your test class with `@AutoConfigureStubRunner`. In the annotation, provide the
@@ -870,7 +897,7 @@ can also provide the offline work switch (`StubRunnerProperties.StubsMode.LOCAL`
[source,groovy,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=autoconfigure_stubrunner,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=autoconfigure_stubrunner,indent=0]
----
Now, when you run your tests, you see something like this:
@@ -909,8 +936,8 @@ As a reminder, you can see the initial implementation here:
[source,java,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0]
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0]
}
----
@@ -926,14 +953,14 @@ You must add the dependencies needed by the autogenerated tests:
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0]
----
In the configuration of the Maven plugin, pass the `packageWithBaseClasses` property
[source,xml,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0]
----
IMPORTANT: This example uses "convention based" naming by setting the
@@ -949,7 +976,7 @@ start the server side `FraudDetectionController`.
[source,java,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/test/java/com/example/fraud/FraudBase.java[]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/test/java/com/example/fraud/FraudBase.java[]
----
Now, if you run the `./mvnw clean install`, you get something like this:
@@ -1006,9 +1033,9 @@ implementation:
[source,java,indent=0]
----
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0]
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=new_impl,indent=0]
Unresolved directive in verifier_introduction.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=new_impl,indent=0]
Unresolved directive in _verifier_how_it_works.adoc - include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0]
}
----
@@ -1052,9 +1079,7 @@ achieving the same thing by changing the properties.
[source,yaml,indent=0]
----
stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: https://repo.spring.io/libs-snapshot
Unresolved directive in _verifier_how_it_works.adoc - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/master/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
----
That's it!
@@ -1124,8 +1149,8 @@ your test. The following code shows an example:
[source,java,indent=0]
----
Unresolved directive in spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsTests.java[tags=wiremock_test1]
Unresolved directive in spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsTests.java[tags=wiremock_test2]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsTests.java[tags=wiremock_test1]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsTests.java[tags=wiremock_test2]
----
To start the stub server on a different port use (for example),
@@ -1169,7 +1194,7 @@ stubs are stored under `/META-INF/group-id/artifact-id/versions/mappings/` folde
[source,java,indent=0]
----
Unresolved directive in spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/AutoConfigureWireMockFilesApplicationWithUrlResourceTests.java[tags=load_all_stubs]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/AutoConfigureWireMockFilesApplicationWithUrlResourceTests.java[tags=load_all_stubs]
----
=== Using Files to Specify the Stub Bodies
@@ -1197,8 +1222,8 @@ instance, as shown in the following example:
[source,java,indent=0]
----
Unresolved directive in spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsClassRuleTests.java[tags=wiremock_test1]
Unresolved directive in spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsClassRuleTests.java[tags=wiremock_test2]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsClassRuleTests.java[tags=wiremock_test1]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsClassRuleTests.java[tags=wiremock_test2]
----
The `@ClassRule` means that the server shuts down after all the methods in this class
@@ -1260,7 +1285,7 @@ a Spring `MockRestServiceServer`. The following code shows an example:
[source,java,indent=0]
----
Unresolved directive in spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsMockServerApplicationTests.java[tags=wiremock_test]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{doc_samples}/src/test/java/com/example/WiremockForDocsMockServerApplicationTests.java[tags=wiremock_test]
----
The `baseUrl` value is prepended to all mock calls, and the `stubs()` method takes a stub
@@ -1285,9 +1310,9 @@ Example:
[source,java,indent=0]
----
Unresolved directive in spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/AutoConfigureWireMockConfigurationCustomizerTests.java[tags=customizer_1]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/AutoConfigureWireMockConfigurationCustomizerTests.java[tags=customizer_1]
// perform your customization here
Unresolved directive in spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/AutoConfigureWireMockConfigurationCustomizerTests.java[tags=customizer_2]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/AutoConfigureWireMockConfigurationCustomizerTests.java[tags=customizer_2]
----
=== Generating Stubs using REST Docs
@@ -1297,7 +1322,30 @@ documentation (for example in Asciidoctor format) for an HTTP API with Spring Mo
or `WebTestClient` or Rest Assured. At the same time that you generate documentation for your API, you can also
generate WireMock stubs by using Spring Cloud Contract WireMock. To do so, write your
normal REST Docs test cases and use `@AutoConfigureRestDocs` to have stubs be
automatically generated in the REST Docs output directory. The following code shows an
automatically generated in the REST Docs output directory.
[plantuml, rest-docs, png]
----
"API Producer"->"API Producer": add Spring Cloud Contract (SCC) \nStub Runner dependency
"API Producer"->"API Producer": setup stub jar assembly
"API Producer"->"API Producer": write and setup REST Docs tests
"API Producer"->"Build": run build
"Build"->"REST Docs": generate API \ndocumentation
"REST Docs"->"SCC": generate stubs from the \nREST Docs tests
"REST Docs"->"SCC": generate contracts from the \nREST Docs tests
"Build"->"Build": assemble stubs jar with \nstubs and contracts
"Build"->"Nexus / Artifactory": upload contracts \nand stubs and the project arifact
"Build"->"API Producer": Build successful
"API Consumer"->"API Consumer": add SCC Stub Runner \ndependency
"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test
"SCC Stub Runner"->"Nexus / Artifactory": test asks for [API Producer] stubs
"Nexus / Artifactory"->"SCC Stub Runner": fetch the [API Producer] stubs
"SCC Stub Runner"->"SCC Stub Runner": run in memory\n HTTP server stubs
"API Consumer"->"SCC Stub Runner": send a request \nto the HTTP server stub
"SCC Stub Runner"->"API Consumer": communication is correct
----
The following code shows an
example using `MockMvc`:
[source,java,indent=0]
@@ -1461,7 +1509,7 @@ Consider the following test:
[source,java]
----
Unresolved directive in spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/restdocs/ContractDslSnippetTests.java[tags=contract_snippet]
Unresolved directive in _spring-cloud-wiremock.adoc - include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/restdocs/ContractDslSnippetTests.java[tags=contract_snippet]
----
The preceding test creates the stub presented in the previous section, generating both
@@ -1511,185 +1559,7 @@ You can read more about Spring Cloud Contract Verifier by reading the
== Contributing
:spring-cloud-build-branch: master
Spring Cloud is released under the non-restrictive Apache 2.0 license,
and follows a very standard Github development process, using Github
tracker for issues and merging pull requests into master. If you want
to contribute even something trivial please do not hesitate, but
follow the guidelines below.
=== Sign the Contributor License Agreement
Before we accept a non-trivial patch or pull request we will need you to sign the
https://cla.pivotal.io/sign/spring[Contributor License Agreement].
Signing the contributor's agreement does not grant anyone commit rights to the main
repository, but it does mean that we can accept your contributions, and you will get an
author credit if we do. Active contributors might be asked to join the core team, and
given the ability to merge pull requests.
=== Code of Conduct
This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of
conduct]. By participating, you are expected to uphold this code. Please report
unacceptable behavior to spring-code-of-conduct@pivotal.io.
=== Code Conventions and Housekeeping
None of these is essential for a pull request, but they will all help. They can also be
added after the original pull request but before a merge.
* Use the Spring Framework code format conventions. If you use Eclipse
you can import formatter settings using the
`eclipse-code-formatter.xml` file from the
https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring
Cloud Build] project. If using IntelliJ, you can use the
https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter
Plugin] to import the same file.
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
`@author` tag identifying you, and preferably at least a paragraph on what the class is
for.
* Add the ASF license header comment to all new `.java` files (copy from existing files
in the project)
* Add yourself as an `@author` to the .java files that you modify substantially (more
than cosmetic changes).
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
* A few unit tests would help a lot as well -- someone has to do it.
* If no-one else is using your branch, please rebase it against the current master (or
other target branch in the main project).
* When writing a commit message please follow https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
message (where XXXX is the issue number).
=== Checkstyle
Spring Cloud Build comes with a set of checkstyle rules. You can find them in the `spring-cloud-build-tools` module. The most notable files under the module are:
.spring-cloud-build-tools/
----
└── src
   ├── checkstyle
   │   └── checkstyle-suppressions.xml <3>
   └── main
   └── resources
   ├── checkstyle-header.txt <2>
   └── checkstyle.xml <1>
----
<1> Default Checkstyle rules
<2> File header setup
<3> Default suppression rules
==== Checkstyle configuration
Checkstyle rules are *disabled by default*. To add checkstyle to your project just define the following properties and plugins.
.pom.xml
----
<properties>
<maven-checkstyle-plugin.failsOnError>true</maven-checkstyle-plugin.failsOnError> <1>
<maven-checkstyle-plugin.failsOnViolation>true
</maven-checkstyle-plugin.failsOnViolation> <2>
<maven-checkstyle-plugin.includeTestSourceDirectory>true
</maven-checkstyle-plugin.includeTestSourceDirectory> <3>
</properties>
<build>
<plugins>
<plugin> <4>
<groupId>io.spring.javaformat</groupId>
<artifactId>spring-javaformat-maven-plugin</artifactId>
</plugin>
<plugin> <5>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>
</plugins>
<reporting>
<plugins>
<plugin> <5>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>
</plugins>
</reporting>
</build>
----
<1> Fails the build upon Checkstyle errors
<2> Fails the build upon Checkstyle violations
<3> Checkstyle analyzes also the test sources
<4> Add the Spring Java Format plugin that will reformat your code to pass most of the Checkstyle formatting rules
<5> Add checkstyle plugin to your build and reporting phases
If you need to suppress some rules (e.g. line length needs to be longer), then it's enough for you to define a file under `${project.root}/src/checkstyle/checkstyle-suppressions.xml` with your suppressions. Example:
.projectRoot/src/checkstyle/checkstyle-suppresions.xml
----
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
"-//Puppy Crawl//DTD Suppressions 1.1//EN"
"https://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
<suppress files=".*ConfigServerApplication\.java" checks="HideUtilityClassConstructor"/>
<suppress files=".*ConfigClientWatch\.java" checks="LineLengthCheck"/>
</suppressions>
----
It's advisable to copy the `${spring-cloud-build.rootFolder}/.editorconfig` and `${spring-cloud-build.rootFolder}/.springformat` to your project. That way, some default formatting rules will be applied. You can do so by running this script:
```bash
$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/.editorconfig -o .editorconfig
$ touch .springformat
```
=== IDE setup
==== Intellij IDEA
In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin.
The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools[Spring Cloud Build] project.
.spring-cloud-build-tools/
----
└── src
   ├── checkstyle
   │   └── checkstyle-suppressions.xml <3>
   └── main
   └── resources
   ├── checkstyle-header.txt <2>
   ├── checkstyle.xml <1>
   └── intellij
      ├── Intellij_Project_Defaults.xml <4>
      └── Intellij_Spring_Boot_Java_Conventions.xml <5>
----
<1> Default Checkstyle rules
<2> File header setup
<3> Default suppression rules
<4> Project defaults for Intellij that apply most of Checkstyle rules
<5> Project style conventions for Intellij that apply most of Checkstyle rules
.Code style
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-code-style.png[Code style]
Go to `File` -> `Settings` -> `Editor` -> `Code style`. There click on the icon next to the `Scheme` section. There, click on the `Import Scheme` value and pick the `Intellij IDEA code style XML` option. Import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml` file.
.Inspection profiles
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-inspections.png[Code style]
Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon next to the `Profile` section. There, click on the `Import Profile` and import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml` file.
.Checkstyle
To have Intellij work with Checkstyle, you have to install the `Checkstyle` plugin. It's advisable to also install the `Assertions2Assertj` to automatically convert the JUnit assertions
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-checkstyle.png[Checkstyle]
Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables:
- `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL.
- `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL.
- `checkstyle.additional.suppressions.file` - this variable corresponds to suppressions in your local project. E.g. you're working on `spring-cloud-contract`. Then point to the `project-root/src/checkstyle/checkstyle-suppressions.xml` folder. Example for `spring-cloud-contract` would be: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`.
IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources.
Unresolved directive in README.adoc - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]
== How to build it