Polish
This commit is contained in:
Marcin Grzejszczak
@@ -1295,7 +1295,7 @@ TIP: As you can see, it is much better if you name your contracts because doing
|
||||
your tests far more meaningful.
|
||||
|
||||
[[contract-stateful-contracts]]
|
||||
== Stateful Contracts
|
||||
=== Stateful Contracts
|
||||
|
||||
Stateful contracts (known also as scenarios) are contract definitions that should be read in order. This might be useful in the following situations:
|
||||
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
[[features-jax-rs]]
|
||||
== JAX-RS
|
||||
[[feature-integrations]]
|
||||
== Integrations
|
||||
include::_attributes.adoc[]
|
||||
|
||||
[[features-jax-rs]]
|
||||
=== JAX-RS
|
||||
|
||||
The Spring Cloud Contract supports the JAX-RS 2 Client API. The base class needs
|
||||
to define `protected WebTarget webTarget` and server initialization. The only option for
|
||||
testing JAX-RS API is to start a web server. Also, a request with a body needs to have a
|
||||
@@ -21,15 +24,10 @@ The following example shows a generated test API:
|
||||
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/JaxRsClientMethodBuilderSpec.groovy[tags=jaxrs,indent=0]
|
||||
----
|
||||
|
||||
[[contract-webflux]]
|
||||
== WebFlux
|
||||
|
||||
Spring Cloud Contract offers two ways of working with WebFlux.
|
||||
|
||||
[[contract-webtestclient]]
|
||||
[[feature-webflux]]
|
||||
=== WebFlux with WebTestClient
|
||||
|
||||
One of them is via the `WebTestClient` mode.
|
||||
You can work with WebFlux via the `WebTestClient` mode.
|
||||
|
||||
====
|
||||
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
|
||||
@@ -74,7 +72,9 @@ public abstract class BeerRestBase {
|
||||
}
|
||||
----
|
||||
|
||||
[[contract-webflux-explicit]]
|
||||
IMPORTANT: The `WebTestClient` mode is faster than the `EXPLICIT` mode
|
||||
|
||||
[[feature-webflux-explicit]]
|
||||
=== WebFlux with Explicit mode
|
||||
|
||||
Another way is with the `EXPLICIT` mode in your generated tests
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
include::_attributes.adoc[]
|
||||
|
||||
[[features-messaging]]
|
||||
== Messaging
|
||||
include::_attributes.adoc[]
|
||||
|
||||
Spring Cloud Contract lets you verify applications that use messaging as a
|
||||
means of communication. All of the integrations shown in this document work with Spring,
|
||||
but you can also create one of your own and use that.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
[[features-stub-runner-features-stub-runner]]
|
||||
[[features-stub-runner]]
|
||||
== Spring Cloud Contract Stub Runner
|
||||
|
||||
One of the issues that you might encounter while using Spring Cloud Contract Verifier is
|
||||
@@ -9,7 +9,7 @@ Copying the JSON files and setting the client side for messaging manually is out
|
||||
question. That is why we introduced Spring Cloud Contract Stub Runner. It can
|
||||
automatically download and run the stubs for you.
|
||||
|
||||
[[features-stub-runner-features-stub-runner-snapshot-versions]]
|
||||
[[features-stub-runner-snapshot-versions]]
|
||||
=== Snapshot versions
|
||||
|
||||
Add the additional snapshot repository to your `build.gradle` file to use snapshot
|
||||
@@ -77,8 +77,7 @@ You can pick the following options of acquiring stubs
|
||||
- Classpath scanning solution that searches classpath via pattern to retrieve stubs
|
||||
- Write your own implementation of the `org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder` for full customization
|
||||
|
||||
// TODO: Fix link
|
||||
The latter example is described in the <<custom_stub_runner, Custom Stub Runner>> section.
|
||||
The latter example is described in the <<advanced.adoc#customization-custom-stub-runner, Custom Stub Runner>> section.
|
||||
|
||||
[[features-stub-runner-downloading-stub]]
|
||||
===== Stub downloading
|
||||
@@ -382,8 +381,7 @@ include::{stubrunner_core_path}/src/test/java/org/springframework/cloud/contract
|
||||
----
|
||||
====
|
||||
|
||||
//TODO: Fix link
|
||||
Check the *Common properties for JUnit and Spring* for more information on how to apply global configuration of Stub Runner.
|
||||
Check the <<features-stub-runner-common-properties-junit-spring>> for more information on how to apply global configuration of Stub Runner.
|
||||
|
||||
IMPORTANT: To use the JUnit rule or JUnit 5 extension together with messaging, you have to provide an implementation of the
|
||||
`MessageVerifier` interface to the rule builder (e.g. `rule.messageVerifier(new MyMessageVerifier())`).
|
||||
|
||||
@@ -193,8 +193,7 @@ that will start the standalone version of Stub Runner.
|
||||
[[docker-stubrunner-env-vars]]
|
||||
=== Environment variables
|
||||
|
||||
//TODO: Fix the link
|
||||
Just execute the docker image. You can pass any of the <<common-properties-junit-spring>>
|
||||
Just execute the docker image. You can pass any of the <<project-features.adoc#features-stub-runner-common-properties-junit-spring, Common Properties for JUnit and Spring>>
|
||||
as environment variables. The convention is that all the
|
||||
letters should be upper case. The camel case notation should
|
||||
and the dot (`.`) should be separated via underscore (`_`). E.g.
|
||||
|
||||
@@ -80,15 +80,22 @@ Need more details about {project-full-name}'s core features?
|
||||
<<project-features.adoc#features, The following content is for you>>:
|
||||
|
||||
* *Core Features:*
|
||||
<<{project-name}-features.adoc#contract-features-spring-application, SpringApplication>> |
|
||||
<<{project-name}-features.adoc#contract-features-external-config, External Configuration>>
|
||||
<<project-features.adoc#contract-dsl, Contract DSL>> |
|
||||
<<project-features.adoc#features-messaging, Messaging>>
|
||||
* *Integrations:*
|
||||
<<project-features.adoc#features-jax-rs, JAX-RS>> |
|
||||
<<project-features.adoc#features-webflux, WebFlux>> |
|
||||
<<project-features.adoc#features-context-paths, Context Paths>> |
|
||||
<<project-features.adoc#features-rest-docs, RESTDocs>>
|
||||
* *Modules:*
|
||||
<<project-features.adoc#features-stub-runner, Stub Runner>> |
|
||||
<<project-features.adoc#features-wiremock, WireMock>>
|
||||
* *Build tools:*
|
||||
link:maven-project.html[Maven] |
|
||||
link:gradle-project.html[Gradle] |
|
||||
link:docker-project.html[Docker]
|
||||
|
||||
|
||||
|
||||
== Advanced Topics
|
||||
Finally, we have a few topics for more advanced users:
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ The `0.1.0` release took place on 26 Jan 2015 and it became stable with `1.0.0`
|
||||
|
||||
Assume that we have a system consisting of multiple microservices:
|
||||
|
||||
image::images/Deps.png[Microservices Architecture]
|
||||
image::Deps.png[Microservices Architecture]
|
||||
|
||||
[[getting-started-introducing-spring-cloud-contract-testing-issues]]
|
||||
==== Testing issues
|
||||
@@ -76,7 +76,7 @@ To solve the aforementioned issues, Spring Cloud Contract was created. The main
|
||||
whole world of microservices. If you work on stubs, then the only applications you need
|
||||
are those that your application directly uses.
|
||||
|
||||
image::images/Stubs2.png[Stubbed Services]
|
||||
image::Stubs2.png[Stubbed Services]
|
||||
|
||||
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
|
||||
@@ -108,8 +108,8 @@ As consumers of services, we need to define what exactly we want to achieve. We
|
||||
formulate our expectations. That is why we write contracts. In other words a contract is an agreement on how the API / message communication should look like. Let's look at the following example
|
||||
|
||||
Assume that you want to send a request containing the ID of a client company and the
|
||||
amount it wants to borrow from us. You also want to send it to the /fraudcheck url via
|
||||
the PUT method.
|
||||
amount it wants to borrow from us. You also want to send it to the `/fraudcheck` url via
|
||||
the `PUT` method.
|
||||
|
||||
====
|
||||
[source,groovy,indent=0,role="primary"]
|
||||
@@ -157,7 +157,7 @@ You can find a somewhat longer tour
|
||||
[[getting-started-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`.
|
||||
|
||||
@@ -653,6 +653,7 @@ For simplicity we will use the following acronyms:
|
||||
- Fraud Detection - FD - the http server
|
||||
- Spring Cloud Contract - SCC
|
||||
|
||||
[[getting-started-cdc-consumer]]
|
||||
=== Consumer side (Loan Issuance)
|
||||
|
||||
As a developer of the Loan Issuance service (a consumer of the Fraud Detection server), you might do the following steps:
|
||||
@@ -700,7 +701,8 @@ Let's start with the Loan Issuance flow:
|
||||
"Loan\nIssuance"->"Fraud\nDetection": send a pull request\nwith the\nsuggested contracts
|
||||
----
|
||||
|
||||
*Start doing TDD by writing a test for your feature.*
|
||||
[[getting-started-cdc-consumer-start]]
|
||||
==== Start doing TDD by writing a test for your feature
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
@@ -710,7 +712,8 @@ include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com
|
||||
Assume that you have written a test of your new feature. If a loan application for a big
|
||||
amount is received, the system should reject that loan application with some description.
|
||||
|
||||
*Write the missing implementation.*
|
||||
[[getting-started-cdc-consumer-write]]
|
||||
==== Write the missing implementation
|
||||
|
||||
At some point in time, you need to send a request to the Fraud Detection service. Assume
|
||||
that you need to send the request containing the ID of the client and the amount the
|
||||
@@ -727,7 +730,8 @@ application runs on `8090`.
|
||||
If you start the test at this point, it breaks, because no service currently runs on port
|
||||
`8080`.
|
||||
|
||||
*Clone the Fraud Detection service repository locally.*
|
||||
[[getting-started-cdc-consumer-clone]]
|
||||
==== Clone the Fraud Detection service repository locally
|
||||
|
||||
You can start by playing around with the server side contract. To do so, you must first
|
||||
clone it.
|
||||
@@ -737,7 +741,8 @@ clone it.
|
||||
$ git clone https://your-git-server.com/server-side.git local-http-server-repo
|
||||
----
|
||||
|
||||
*Define the contract locally in the repo of Fraud Detection service.*
|
||||
[[getting-started-cdc-consumer-define]]
|
||||
==== Define the contract locally in the repo of Fraud Detection service
|
||||
|
||||
As a consumer, you need to define what exactly you want to achieve. You need to formulate
|
||||
your expectations. To do so, write the following contract:
|
||||
@@ -766,9 +771,7 @@ Contract lets you define parts of a JSON block, a URL, etc., which are dynamic.
|
||||
of an identifier or a timestamp, you need not hardcode a value. You want to allow some
|
||||
different ranges of values. To enable ranges of values, you can set regular expressions
|
||||
matching those values for the consumer side. You can provide the body by means of either
|
||||
a map notation or String with interpolations.
|
||||
//TODO: Ensure that the links are correct
|
||||
Consult the <<contract-dsl>> section for more information. We highly recommend using the map notation!
|
||||
a map notation or String with interpolations. We highly recommend using the map notation!
|
||||
|
||||
TIP: You must understand the map notation in order to set up contracts. Please read the
|
||||
https://groovy-lang.org/json.html[Groovy docs regarding JSON].
|
||||
@@ -789,7 +792,8 @@ the `rejectionReason` field having value `Amount too high`,
|
||||
Once you are ready to check the API in practice in the integration tests, you need to
|
||||
install the stubs locally.
|
||||
|
||||
*Add the Spring Cloud Contract Verifier plugin.*
|
||||
[[getting-started-cdc-consumer-add]]
|
||||
==== Add the Spring Cloud Contract Verifier plugin
|
||||
|
||||
We can add either a Maven or a Gradle plugin. In this example, you see how to add Maven.
|
||||
First, add the `Spring Cloud Contract` BOM.
|
||||
@@ -849,7 +853,8 @@ The following line is extremely important:
|
||||
It confirms that the stubs of the `http-server` have been installed in the local
|
||||
repository.
|
||||
|
||||
*Run the integration tests.*
|
||||
[[getting-started-cdc-consumer-run]]
|
||||
==== Run the integration tests
|
||||
|
||||
In order to profit from the Spring Cloud Contract Stub Runner functionality of automatic
|
||||
stub downloading, you must do the following in your consumer side project (`Loan
|
||||
@@ -896,7 +901,8 @@ This output means that Stub Runner has found your stubs and started a server for
|
||||
with group id `com.example`, artifact id `http-server` with version `0.0.1-SNAPSHOT` of
|
||||
the stubs and with `stubs` classifier on port `8080`.
|
||||
|
||||
*File a pull request.*
|
||||
[[getting-started-cdc-consumer-file]]
|
||||
==== File a pull request
|
||||
|
||||
What you have done until now is an iterative process. You can play around with the
|
||||
contract, install it locally, and work on the consumer side until the contract works as
|
||||
@@ -905,6 +911,7 @@ you wish.
|
||||
Once you are satisfied with the results and the test passes, publish a pull request to
|
||||
the server side. Currently, the consumer side work is done.
|
||||
|
||||
[[getting-started-cdc-producer]]
|
||||
=== Producer side (Fraud Detection server)
|
||||
|
||||
As a developer of the Fraud Detection server (a server to the Loan Issuance service) we would like to:
|
||||
@@ -935,7 +942,8 @@ Let's look at the Fraud Detection flow:
|
||||
"CI"->"Stub Storage": build successful,\nupload artifacts
|
||||
----
|
||||
|
||||
*Take over the pull request.*
|
||||
[[getting-started-cdc-producer-pr]]
|
||||
==== Take over the pull request
|
||||
|
||||
As a reminder, you can see the initial implementation here:
|
||||
|
||||
@@ -1029,7 +1037,8 @@ headers, and body defined in the contract. It also is expecting precisely define
|
||||
in the response. In other words, you have the `red` part of `red`, `green`, and
|
||||
`refactor`. It is time to convert the `red` into the `green`.
|
||||
|
||||
*Write the missing implementation.*
|
||||
[[getting-started-cdc-producer-impl]]
|
||||
==== Write the missing implementation
|
||||
|
||||
Because you know the expected input and expected output, you can write the missing
|
||||
implementation:
|
||||
@@ -1046,7 +1055,8 @@ When you execute `./mvnw clean install` again, the tests pass. Since the `Spring
|
||||
Contract Verifier` plugin adds the tests to the `generated-test-sources`, you can
|
||||
actually run those tests from your IDE.
|
||||
|
||||
*Deploy your app.*
|
||||
[[getting-started-cdc-producer-deploy]]
|
||||
==== Deploy your app
|
||||
|
||||
Once you finish your work, you can deploy your change. First, merge the branch:
|
||||
|
||||
@@ -1060,6 +1070,7 @@ $ git push origin master
|
||||
Your CI might run something like `./mvnw clean deploy`, which would publish both the
|
||||
application and the stub artifacts.
|
||||
|
||||
[[getting-started-cdc-consumer-final]]
|
||||
=== Consumer Side (Loan Issuance) Final Step
|
||||
|
||||
As a developer of the Loan Issuance service (a consumer of the Fraud Detection server) we will want to:
|
||||
@@ -1067,8 +1078,7 @@ As a developer of the Loan Issuance service (a consumer of the Fraud Detection s
|
||||
- merge our feature branch to `master`
|
||||
- switch to online mode of working
|
||||
|
||||
|
||||
[plantuml, getting-started-cdc-client, png]
|
||||
[plantuml, getting-started-cdc-client-final, png]
|
||||
----
|
||||
"Loan\nIssuance"->"Loan\nIssuance": merge the\nfeature branch\nto master branch
|
||||
"Loan\nIssuance"->"Loan\nIssuance": setup SCC Stub Runner\nto fetch stubs\nfrom Stub Storage
|
||||
@@ -1084,7 +1094,8 @@ As a developer of the Loan Issuance service (a consumer of the Fraud Detection s
|
||||
"Loan\nIssuance"->"Loan\nIssuance": the test passes successfully
|
||||
----
|
||||
|
||||
*Merge branch to master.*
|
||||
[[getting-started-cdc-consumer-final-merge]]
|
||||
==== Merge branch to master
|
||||
|
||||
[source,bash,indent=0]
|
||||
----
|
||||
@@ -1092,7 +1103,8 @@ $ git checkout master
|
||||
$ git merge --no-ff contract-change-pr
|
||||
----
|
||||
|
||||
*Work online.*
|
||||
[[getting-started-cdc-consumer-final-online]]
|
||||
==== Work online
|
||||
|
||||
Now you can disable the offline work for Spring Cloud Contract Stub Runner and indicate
|
||||
where the repository with your stubs is located. At this moment the stubs of the server
|
||||
@@ -1116,11 +1128,10 @@ https://spring.io/guides/[getting started] guides that solve specific "`How do I
|
||||
with Spring?`" problems. We also have {project-full-name}-specific
|
||||
"`<<howto.adoc#howto, How-to>>`" reference documentation.
|
||||
|
||||
Otherwise, the next logical step is to read _<<using.adoc#using>>_. If
|
||||
Otherwise, the next logical step is to read _<<using.adoc#using, Using {project-full-name}>>_. If
|
||||
you are really impatient, you could also jump ahead and read about
|
||||
_<<project-features.adoc#project-features, {project-full-name} features>>_.
|
||||
|
||||
// TODO: Check if we can link courses
|
||||
In addition to that you can check out the following videos:
|
||||
|
||||
- "Consumer Driven Contracts and Your Microservice Architecture" by Olga Maciaszek-Sharma and Marcin Grzejszczak
|
||||
|
||||
@@ -32,8 +32,7 @@ Spring Cloud Contract Verifier stand out on the "market" of Consumer Driven Cont
|
||||
[[how-to-not-write-contracts-in-groovy]]
|
||||
== How can I write contracts in a language different than Groovy?
|
||||
|
||||
// TODO: Add a link
|
||||
No problem. You can write a contract in YAML! Check this section for more information
|
||||
No problem. You can write a contract in YAML! Check <<project-features.adoc#contract-dsl, this section>> for more information.
|
||||
|
||||
We are working on allowing more ways of describing the contracts. You can check the {github-issues}[github-issues] for more information.
|
||||
|
||||
@@ -125,8 +124,7 @@ How can you then provide one time a matcher for the consumer and a concrete valu
|
||||
In Spring Cloud Contract we're allowing you to provide a *dynamic value*. That means that it can differ for both
|
||||
sides of the communication.
|
||||
|
||||
// TODO: Ensure that the link is correct
|
||||
You can read more about this in the <<contract-dsl>> section.
|
||||
You can read more about this in the <<project-features.adoc#contract-dsl, Contract DSL>> section.
|
||||
|
||||
IMPORTANT: Please read the https://groovy-lang.org/json.html[Groovy docs related to JSON] to understand how to
|
||||
properly structure the request / response bodies.
|
||||
|
||||
@@ -9,8 +9,8 @@ The reference documentation consists of the following sections:
|
||||
[horizontal]
|
||||
<<legal.adoc#legal-information,Legal>> :: Legal information.
|
||||
<<documentation-overview.adoc#contract-documentation,Documentation Overview>> :: About the Documentation, Getting Help, First Steps, and more.
|
||||
<<getting-started.adoc#getting-started,Getting Started>> :: Introducing {project-full-name}, System Requirements, Developing Your First {project-full-name} based Application
|
||||
<<getting-started.adoc#getting-started,Getting Started>> :: Introducing {project-full-name}, Developing Your First {project-full-name} based Application
|
||||
<<using.adoc#using,Using {project-full-name}>> :: {project-full-name} usage examples and workflows
|
||||
<<project-features.adoc#features,{project-full-name} Features>> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more.W
|
||||
<<project-features.adoc#features,{project-full-name} Features>> :: Contract DSL, Messaging, Spring Cloud Contract Stub Runner, Spring Cloud Contract WireMock
|
||||
<<project-features.adoc#features-build-tools,Build Tools>> :: Maven Plugin, Gradle Plugin, Docker
|
||||
<<howto.adoc#howto,"`How-to`" Guides>> :: Stubs versioning, Pact integration, Debugging, and more.
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
include::_attributes.adoc[]
|
||||
|
||||
This section goes into more detail about how you should use {project-full-name}. It covers topics
|
||||
such as description of flows of how to work with {{project-full-name}}. We also
|
||||
cover some {{project-full-name}} best practices.
|
||||
such as description of flows of how to work with {project-full-name}. We also
|
||||
cover some {project-full-name} best practices.
|
||||
|
||||
If you are starting out with {project-full-name}, you should probably read the
|
||||
_<<getting-started.adoc#getting-started, Getting Started>>_ guide before diving into this
|
||||
@@ -778,4 +778,4 @@ Since the consumer flow isn't affected by the tool used to generate the stubs, y
|
||||
You should now understand how you can use {project-full-name} and some best practices that you
|
||||
should follow. You can now go on to learn about specific
|
||||
_<<project-features#project-features, {project-full-name} features>>_ in depth, or you could
|
||||
skip ahead and read about the ...
|
||||
skip ahead and read about the _link:advanced.html[advanced features of {project-full-name}]_.
|
||||
|
||||
Reference in New Issue
Block a user