diff --git a/docs/src/main/asciidoc/_project-features-contract.adoc b/docs/src/main/asciidoc/_project-features-contract.adoc index df80880e4a..f9d721b10c 100644 --- a/docs/src/main/asciidoc/_project-features-contract.adoc +++ b/docs/src/main/asciidoc/_project-features-contract.adoc @@ -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: diff --git a/docs/src/main/asciidoc/_project-features-flows.adoc b/docs/src/main/asciidoc/_project-features-flows.adoc index 7ef5b542ea..d936a3eaf3 100644 --- a/docs/src/main/asciidoc/_project-features-flows.adoc +++ b/docs/src/main/asciidoc/_project-features-flows.adoc @@ -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 diff --git a/docs/src/main/asciidoc/_project-features-messaging.adoc b/docs/src/main/asciidoc/_project-features-messaging.adoc index e43743bb16..b71316b584 100644 --- a/docs/src/main/asciidoc/_project-features-messaging.adoc +++ b/docs/src/main/asciidoc/_project-features-messaging.adoc @@ -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. diff --git a/docs/src/main/asciidoc/_project-features-stubrunner.adoc b/docs/src/main/asciidoc/_project-features-stubrunner.adoc index 5d64dc5bef..cfa0ff4a4b 100644 --- a/docs/src/main/asciidoc/_project-features-stubrunner.adoc +++ b/docs/src/main/asciidoc/_project-features-stubrunner.adoc @@ -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 <> section. +The latter example is described in the <> 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 <> 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())`). diff --git a/docs/src/main/asciidoc/docker-project.adoc b/docs/src/main/asciidoc/docker-project.adoc index 67185d90f1..3d29cff4ce 100644 --- a/docs/src/main/asciidoc/docker-project.adoc +++ b/docs/src/main/asciidoc/docker-project.adoc @@ -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 <> +Just execute the docker image. You can pass any of the <> 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. diff --git a/docs/src/main/asciidoc/documentation-overview.adoc b/docs/src/main/asciidoc/documentation-overview.adoc index b70c364876..8e9d44faeb 100644 --- a/docs/src/main/asciidoc/documentation-overview.adoc +++ b/docs/src/main/asciidoc/documentation-overview.adoc @@ -80,15 +80,22 @@ Need more details about {project-full-name}'s core features? <>: * *Core Features:* -<<{project-name}-features.adoc#contract-features-spring-application, SpringApplication>> | -<<{project-name}-features.adoc#contract-features-external-config, External Configuration>> +<> | +<> +* *Integrations:* +<> | +<> | +<> | +<> +* *Modules:* +<> | +<> * *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: diff --git a/docs/src/main/asciidoc/getting-started.adoc b/docs/src/main/asciidoc/getting-started.adoc index ce8d92c0ee..2e6a4a3945 100644 --- a/docs/src/main/asciidoc/getting-started.adoc +++ b/docs/src/main/asciidoc/getting-started.adoc @@ -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 <> 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 "`<>`" reference documentation. -Otherwise, the next logical step is to read _<>_. If +Otherwise, the next logical step is to read _<>_. If you are really impatient, you could also jump ahead and read about _<>_. -// 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 diff --git a/docs/src/main/asciidoc/howto.adoc b/docs/src/main/asciidoc/howto.adoc index e3e0f1db3c..9094dfa857 100644 --- a/docs/src/main/asciidoc/howto.adoc +++ b/docs/src/main/asciidoc/howto.adoc @@ -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 <> 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 <> section. +You can read more about this in the <> 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. diff --git a/docs/src/main/asciidoc/index.htmladoc b/docs/src/main/asciidoc/index.htmladoc index eb633d129e..4ee1bab1c8 100644 --- a/docs/src/main/asciidoc/index.htmladoc +++ b/docs/src/main/asciidoc/index.htmladoc @@ -9,8 +9,8 @@ The reference documentation consists of the following sections: [horizontal] <> :: Legal information. <> :: About the Documentation, Getting Help, First Steps, and more. -<> :: Introducing {project-full-name}, System Requirements, Developing Your First {project-full-name} based Application +<> :: Introducing {project-full-name}, Developing Your First {project-full-name} based Application <> :: {project-full-name} usage examples and workflows -<> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more.W +<> :: Contract DSL, Messaging, Spring Cloud Contract Stub Runner, Spring Cloud Contract WireMock <> :: Maven Plugin, Gradle Plugin, Docker <> :: Stubs versioning, Pact integration, Debugging, and more. diff --git a/docs/src/main/asciidoc/using.adoc b/docs/src/main/asciidoc/using.adoc index 07ddd2d03e..9fa0e8ab80 100644 --- a/docs/src/main/asciidoc/using.adoc +++ b/docs/src/main/asciidoc/using.adoc @@ -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 _<>_ 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 _<>_ 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}]_.