diff --git a/docs/modules/ROOT/pages/README.adoc b/docs/modules/ROOT/pages/README.adoc index f1315d6b54..ac23efd2ea 100644 --- a/docs/modules/ROOT/pages/README.adoc +++ b/docs/modules/ROOT/pages/README.adoc @@ -1,5 +1,5 @@ [[spring-cloud-contract]] -== Spring Cloud Contract += Spring Cloud Contract You always need confidence when pushing new features into a new application or service in a distributed system. To that end, this project provides support for consumer-driven @@ -8,12 +8,12 @@ writing tests, publishing them as assets, and asserting that a contract is kept producers and consumers -- for both HTTP and message-based interactions. [[project-page]] -== Project page += Project page You can read more about Spring Cloud Contract by going to https://spring.io/projects/spring-cloud-contract[the project page] [[contributing]] -== Contributing += Contributing include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/contributing.adoc[] diff --git a/docs/modules/ROOT/pages/_building.adoc b/docs/modules/ROOT/pages/_building.adoc index f1d9168ee1..ced98ca14e 100644 --- a/docs/modules/ROOT/pages/_building.adoc +++ b/docs/modules/ROOT/pages/_building.adoc @@ -1,8 +1,8 @@ [[how-to-build-spring-cloud-contract]] -== How to Build Spring Cloud Contract += How to Build Spring Cloud Contract [[cloning-the-repository-on-windows]] -=== Cloning the repository on Windows +== Cloning the repository on Windows While cloning this project on Windows, some files in the git repository may exceed the Windows maximum file path limit of 255 characters, which may result in an incorrectly (probably partially) checked out repository. @@ -46,7 +46,7 @@ have Docker installed. IMPORTANT: If you want to run the build in offline mode, you must have Maven 3.5.2+ installed. [[project-structure]] -=== Project structure +== Project structure The following listing shows the Spring Cloud Contract folder structure: @@ -86,7 +86,7 @@ The following list describes each of the top-level folders in the project struct - `tests`: Integration tests for different messaging technologies [[commands]] -=== Commands +== Commands To build the core functionality together with the Maven Plugin, you can run the following command: @@ -107,7 +107,7 @@ cd spring-cloud-contract-tools/spring-cloud-contract-gradle-plugin ``` [[helpful-scripts]] -=== Helpful scripts +== Helpful scripts We provide a couple of helpful scripts to build the project. diff --git a/docs/modules/ROOT/pages/_project-features-contract.adoc b/docs/modules/ROOT/pages/_project-features-contract.adoc index 3904cd0916..87af992c6a 100644 --- a/docs/modules/ROOT/pages/_project-features-contract.adoc +++ b/docs/modules/ROOT/pages/_project-features-contract.adoc @@ -1,5 +1,6 @@ [[contract-dsl]] -== Contract DSL += Contract DSL + include::_attributes.adoc[] Spring Cloud Contract supports DSLs written in the following languages: @@ -49,7 +50,7 @@ mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert ==== [[contract-groovy]] -=== Contract DSL in Groovy +== Contract DSL in Groovy If you are not familiar with Groovy, do not worry. You can use Java syntax in the Groovy DSL files as well. @@ -66,7 +67,7 @@ the `Contract` class (`import org.springframework.cloud.spec.Contract`) and then `Contract.make { ... }`. [[contract-java]] -=== Contract DSL in Java +== Contract DSL in Java To write a contract definition in Java, you need to create a class that implements either the `Supplier` interface (for a single contract) or `Supplier>` (for multiple contracts). @@ -99,7 +100,7 @@ contracts { ==== [[contract-kotlin]] -=== Contract DSL in Kotlin +== Contract DSL in Kotlin To get started with writing contracts in Kotlin, you need to start with a (newly created) Kotlin Script file (`.kts`). As with the Java DSL, you can put your contracts in any directory of your choice. @@ -172,12 +173,12 @@ Generally you would use its contract function as follows: `org.springframework.c You can also provide an import to the `contract` function (`import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract`) and then call `contract { ... }`. [[contract-yml]] -=== Contract DSL in YAML +== Contract DSL in YAML To see a schema of a YAML contract, visit the {docs-url}/reference/html/yml-schema.html[YML Schema] page. [[contract-limitations]] -=== Limitations +== Limitations WARNING: The support for verifying the size of JSON arrays is experimental. If you want to turn it on, set the value of the following system property to `true`: @@ -189,7 +190,7 @@ properly when using the Groovy DSL and the `value(consumer(...), producer(...))` is why you should use the Groovy Map notation. [[contract-common-top-elements]] -=== Common Top-Level Elements +== Common Top-Level Elements The following sections describe the most common top-level elements: @@ -201,7 +202,7 @@ The following sections describe the most common top-level elements: * <> [[contract-dsl-description]] -==== Description +=== Description You can add a `description` to your contract. The description is arbitrary text. The following code shows an example: @@ -233,7 +234,7 @@ include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/c ==== [[contract-dsl-name]] -==== Name +=== Name You can provide a name for your contract. Assume that you provide the following name: `should register a user`. If you do so, the name of the autogenerated test is @@ -274,7 +275,7 @@ include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/c ==== [[contract-dsl-ignoring-contracts]] -==== Ignoring Contracts +=== Ignoring Contracts If you want to ignore a contract, you can either set a value for ignored contracts in the plugin configuration or set the `ignored` property on the contract itself. The following @@ -307,7 +308,7 @@ include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/c ==== [[contract-dsl-in-progress]] -==== Contracts in Progress +=== Contracts in Progress A contract in progress does not generate tests on the producer side but does allow generation of stubs. @@ -345,7 +346,7 @@ include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/c You can set the value of the `failOnInProgress` Spring Cloud Contract plugin property to ensure that your build breaks when at least one contract in progress remains in your sources. [[contract-dsl-passing-values-from-files]] -==== Passing Values from Files +=== Passing Values from Files Starting with version `1.2.0`, you can pass values from files. Assume that you have the following resources in your project: @@ -444,7 +445,7 @@ IMPORTANT: You should use this approach whenever you want to work with binary pa both for HTTP and messaging. [[contract-dsl-metadata]] -==== Metadata +=== Metadata You can add `metadata` to your contract. Via the metadata you can pass in configuration to extensions. Below you can find an example of using the `wiremock` key. Its value is a map whose key is `stubMapping` and value being WireMock's `StubMapping` object. Spring Cloud Contract is able to @@ -484,7 +485,7 @@ include::{project-root}/docs/target/metadata.adoc[indent=0] //// [[features-http]] -== Contracts for HTTP += Contracts for HTTP Spring Cloud Contract lets you verify applications that use REST or HTTP as a means of communication. Spring Cloud Contract verifies that, for a request that matches the @@ -494,7 +495,7 @@ generate WireMock stubs that, for any request matching the provided criteria, pr suitable response. [[contract-dsl-http-top-level-elements]] -=== HTTP Top-Level Elements +== HTTP Top-Level Elements You can call the following methods in the top-level closure of a contract definition: @@ -539,7 +540,7 @@ you need to pass a lower number to the `priority` tag or method. For example, a a value of `5` has higher priority than a `priority` with a value of `10`. [[contract-dsl-request]] -=== HTTP Request +== HTTP Request The HTTP protocol requires only the method and the URL to be specified in a request. The same information is mandatory in request definition of the contract. @@ -810,7 +811,7 @@ include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract ==== [[contract-dsl-response]] -=== HTTP Response +== HTTP Response The response must contain an HTTP status code and may contain other information. The following code shows an example: @@ -851,7 +852,7 @@ methods to provide a meaningful status instead of a digit. For example, you can `OK()` for a status `200` or `BAD_REQUEST()` for `400`. [[contract-dsl-dynamic-properties]] -=== Dynamic properties +== Dynamic properties The contract can contain some dynamic properties: timestamps, IDs, and so on. You do not want to force the consumers to stub their clocks to always return the same value of time @@ -869,7 +870,7 @@ For YAML, you can use only the `matchers` section. IMPORTANT: Entries inside the `matchers` must reference existing elements of the payload. For more information, see https://github.com/spring-cloud/spring-cloud-contract/issues/722[this issue]. [[contract-dsl-dynamic-properties-in-body]] -==== Dynamic Properties inside the Body +=== Dynamic Properties inside the Body IMPORTANT: This section is valid only for the Coded DSL (Groovy, Java, and so on). See the <> section for YAML examples of a similar feature. @@ -902,7 +903,7 @@ Both approaches work equally well. The `stub` and `client` methods are aliases o method. Subsequent sections take a closer look at what you can do with those values. [[contract-dsl-regex]] -==== Regular Expressions +=== Regular Expressions IMPORTANT: This section is valid only for the Groovy DSL. See the <> section for YAML examples of a similar feature. @@ -992,7 +993,7 @@ include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.k ==== [[contract-dsl-regex-limitations]] -===== Limitations +==== Limitations CAUTION: Due to certain limitations of the `Xeger` library that generates a string out of a regex, do not use the `$` and `^` signs in your regex if you rely on automatic @@ -1003,7 +1004,7 @@ It causes a `java.lang.StackOverflowError`. Use `$(consumer(LocalDate.now().toSt See https://github.com/spring-cloud/spring-cloud-contract/issues/900[Issue 900]. [[contract-dsl-optional-params]] -==== Passing Optional Parameters +=== Passing Optional Parameters IMPORTANT: This section is valid only for Groovy DSL. See the <> section for YAML examples of a similar feature. @@ -1057,7 +1058,7 @@ include::{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/spr ---- [[contract-dsl-custom-methods]] -==== Calling Custom Methods on the Server Side +=== Calling Custom Methods on the Server Side IMPORTANT: This section is valid only for the Groovy DSL. See the <> section for YAML examples of a similar feature. @@ -1138,7 +1139,7 @@ It should resemble the following code: ---- [[contract-dsl-referencing-request-from-response]] -==== Referencing the Request from the Response +=== Referencing the Request from the Response The best situation is to provide fixed values, but sometimes you need to reference a request in your response. @@ -1368,7 +1369,7 @@ proper values. Additionally, it registers two helper functions: * `jsonpath`: For a given parameter, finds an object in the request body. [[contract-dsl-matchers]] -==== Dynamic Properties in the Matchers Sections +=== Dynamic Properties in the Matchers Sections If you work with https://docs.pact.io/[Pact], the following discussion may seem familiar. Quite a few users are used to having a separation between the body and setting the @@ -1386,7 +1387,7 @@ Currently, Spring Cloud Contract Verifier supports only JSON path-based matchers following matching possibilities: [[coded-dsl]] -===== Coded DSL +==== Coded DSL For the stubs (in tests on the consumer's side): @@ -1432,7 +1433,7 @@ following, depending on the JSON path: * `byNull()`: The value taken from the response in the provided JSON path must be null. [[yaml]] -===== YAML +==== YAML NOTE: See the Groovy section for a detailed explanation of what the types mean. @@ -1648,7 +1649,7 @@ asserted. To fix this, apply the assertion to the whole `$.events` collection and assert it with the `byCommand(...)` method. [[contract-dsl-async]] -=== Asynchronous Support +== Asynchronous Support If you use asynchronous communication on the server side (your controllers are returning `Callable`, `DeferredResult`, and so on), then, inside your contract, you must @@ -1782,7 +1783,7 @@ contract { ==== [[contract-dsl-xml]] -=== XML Support for HTTP +== XML Support for HTTP For HTTP contracts, we also support using XML in the request and response body. The XML body has to be passed within the `body` element @@ -1853,7 +1854,7 @@ public void validate_xmlMatches() throws Exception { ==== [[xml-support-for-namespaces]] -==== XML Support for Namespaces +=== XML Support for Namespaces Namespaced XML is supported. However, any XPath expresssions used to select namespaced content must be updated. Consider the following explicitly namespaced XML document: @@ -1885,7 +1886,7 @@ WARNING: Beware, as the unqualified expressions (`/customer/email/text()` or `*/ result in `""`. Even the child elements have to be referenced with the `local-name` syntax. [[general-namespaced-node-expression-syntax]] -===== General Namespaced Node Expression Syntax +==== General Namespaced Node Expression Syntax - Node using qualified namespace: ``` / @@ -1903,7 +1904,7 @@ NOTE: In some cases, you can omit the `namespace_uri` portion, but doing so may [[contract-dsl-multiple]] -=== Multiple Contracts in One File +== Multiple Contracts in One File You can define multiple contracts in one file. Such a contract might resemble the following example: @@ -2037,7 +2038,7 @@ TIP: It is much better to name your contracts, because doing so makes your tests far more meaningful. [[contract-stateful-contracts]] -=== Stateful Contracts +== Stateful Contracts Stateful contracts (also known as scenarios) are contract definitions that should be read in order. This might be useful in the following situations: diff --git a/docs/modules/ROOT/pages/_project-features-flows.adoc b/docs/modules/ROOT/pages/_project-features-flows.adoc index 7ed809c171..43ff0cda60 100644 --- a/docs/modules/ROOT/pages/_project-features-flows.adoc +++ b/docs/modules/ROOT/pages/_project-features-flows.adoc @@ -1,9 +1,10 @@ [[feature-integrations]] -== Integrations += Integrations + include::_attributes.adoc[] [[features-jax-rs]] -=== 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 @@ -29,7 +30,7 @@ include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract ==== [[feature-webflux]] -=== WebFlux with WebTestClient +== WebFlux with WebTestClient You can work with WebFlux by using WebTestClient. The following listing shows how to configure WebTestClient as the test mode: @@ -82,7 +83,7 @@ public abstract class BeerRestBase { TIP: The `WebTestClient` mode is faster than the `EXPLICIT` mode. [[feature-webflux-explicit]] -=== WebFlux with Explicit Mode +== WebFlux with Explicit Mode You can also use WebFlux with the explicit mode in your generated tests to work with WebFlux. The following example shows how to configure using explicit mode: @@ -128,7 +129,7 @@ include::{samples_url}/producer_webflux/src/test/java/com/example/BeerRestBase.j ==== [[features-custom-mode]] -=== Custom Mode +== Custom Mode IMPORTANT: This mode is experimental and can change in the future. @@ -232,7 +233,7 @@ public abstract class BeerRestBase { ==== [[features-context-paths]] -=== Working with Context Paths +== Working with Context Paths Spring Cloud Contract supports context paths. @@ -294,7 +295,7 @@ context path included (for example, `/my-context-path/url`). that information (for example, in the stubs, you have to call `/my-context-path/url`). [[features-rest-docs]] -=== Working with REST Docs +== Working with REST Docs You can use https://projects.spring.io/spring-restdocs[Spring REST Docs] to generate documentation (for example, in Asciidoc format) for an HTTP API with Spring MockMvc, @@ -478,7 +479,7 @@ number of different ways, including by using document. [[features-rest-docs-contracts]] -==== Generating Contracts with REST Docs +=== Generating Contracts with REST Docs You can also generate Spring Cloud Contract DSL files and documentation with Spring REST Docs. If you do so in combination with Spring Cloud WireMock, you get both the contracts @@ -545,7 +546,7 @@ The generated document (formatted in Asciidoc in this case) contains a formatted contract. The location of this file would be `index/dsl-contract.adoc`. [[features-restdocs-priority-attribute]] -==== Specifying the priority attribute +=== Specifying the priority attribute The method `SpringCloudContractRestDocs.dslContract()` takes an optional Map parameter that allows you to specify additional attributes in the template. @@ -557,7 +558,7 @@ SpringCloudContractRestDocs.dslContract(Map.of("priority", 1)) ---- [[features-restdocs-override]] -==== Overriding the DSL contract template +=== Overriding the DSL contract template By default, the output of the contract is based on a file named `default-dsl-contract-only.snippet`. @@ -601,7 +602,7 @@ Therefore in the example above you should place a file named custom-dsl-template [[features-graphql]] -=== GraphQL +== GraphQL Since https://graphql.org/[GraphQL] is essentially HTTP you can write a contract for it by creating a standard HTTP contract with an additional `metadata` entry with key `verifier` and a mapping `tool=graphql`. @@ -694,7 +695,7 @@ metadata: Adding the metadata section will change the way the default, WireMock stub is built. It will now use the Spring Cloud Contract request matcher, so that e.g. the `query` part of the GraphQL request gets compared against the real request by ignoring whitespaces. [[features-graphql-producer]] -==== Producer Side Setup +=== Producer Side Setup On the producer side your configuration can look as follows. @@ -747,7 +748,7 @@ public abstract class BaseClass { ==== [[features-graphql-consumer]] -==== Consumer Side Setup +=== Consumer Side Setup Example of a consumer side test of the GraphQL API. @@ -786,7 +787,7 @@ public class BeerControllerGraphQLTest { ==== [[features-grpc]] -=== GRPC +== GRPC https://grpc.io/[GRPC] is an RPC framework built on top of HTTP/2 for which Spring Cloud Contract has basic support. @@ -846,7 +847,7 @@ then: ==== [[features-grpc-producer]] -==== Producer Side Setup +=== Producer Side Setup In order to leverage the HTTP/2 support you must set the `CUSTOM` test mode as follow. @@ -917,7 +918,7 @@ public abstract class BeerRestBase { ==== [[features-grpc-consumer]] -==== Consumer Side Setup +=== Consumer Side Setup Example of GRPC consumer side test. Due to the unusual behaviour of the GRPC server side, the stub is unable to return the `grpc-status` header in the proper moment. This is why we need to manually set the return status. diff --git a/docs/modules/ROOT/pages/_project-features-messaging.adoc b/docs/modules/ROOT/pages/_project-features-messaging.adoc index c86790cd13..6fbe5fddf9 100644 --- a/docs/modules/ROOT/pages/_project-features-messaging.adoc +++ b/docs/modules/ROOT/pages/_project-features-messaging.adoc @@ -1,5 +1,6 @@ [[features-messaging]] -== Messaging += Messaging + include::_attributes.adoc[] Spring Cloud Contract lets you verify applications that use messaging as a @@ -7,7 +8,7 @@ means of communication. All of the integrations shown in this document work with but you can also create one of your own and use that. [[contract-dsl-messaging-top-level]] -=== Messaging DSL Top-level Elements +== Messaging DSL Top-level Elements The DSL for messaging looks a little bit different than the one that focuses on HTTP. The following sections explain the differences: @@ -17,7 +18,7 @@ following sections explain the differences: * <> [[contract-dsl-output-triggered-method]] -==== Output Triggered by a Method +=== Output Triggered by a Method The output message can be triggered by calling a method (such as a `Scheduler` when a contract was started and when a message was sent), as shown in the following example: @@ -43,7 +44,7 @@ test that calls that method to trigger the message. On the consumer side, you ca [[contract-dsl-consumer-producer]] -==== Consumer/Producer +=== Consumer/Producer IMPORTANT: This section is valid only for the Groovy DSL. @@ -54,7 +55,7 @@ provides the `consumer` and `producer` methods parts). [[contract-dsl-messaging-common]] -==== Common +=== Common In the `input` or `outputMessage` section, you can call `assertThat` with the name of a `method` (for example, `assertThatMessageIsOnTheQueue()`) that you have defined in the @@ -62,7 +63,7 @@ base class or in a static import. Spring Cloud Contract runs that method in the generated test. [[features-messaging-integrations]] -=== Integrations +== Integrations You can use one of the following integration configurations: @@ -105,7 +106,7 @@ testImplementation(group: 'org.springframework.cloud', name: 'spring-cloud-strea ===== [[features-messaging-manual]] -==== Manual Integration Testing +=== Manual Integration Testing The main interface used by the tests is `org.springframework.cloud.contract.verifier.messaging.MessageVerifierSender` and `org.springframework.cloud.contract.verifier.messaging.MessageVerifierReceiver`. @@ -134,7 +135,7 @@ NOTE: If your tests require stubs as well, then `@AutoConfigureStubRunner` inclu messaging configuration, so you only need the one annotation. [[features-messaging-test-generation]] -=== Producer Side Messaging Test Generation +== Producer Side Messaging Test Generation Having the `input` or `outputMessage` sections in your DSL results in creation of tests on the publisher's side. By default, JUnit 4 tests are created. However, there is also a @@ -180,7 +181,7 @@ include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract ==== [[features-messaging-consumer]] -=== Consumer Stub Generation +== Consumer Stub Generation Unlike in the HTTP part, in messaging, we need to publish the contract definition inside the JAR with a stub. Then it is parsed on the consumer side, and proper stubbed routes are created. @@ -192,7 +193,7 @@ on the classpath and that you want to use Spring AMQP. Then you need to set That way, the only remaining framework is Spring AMQP. [[features-messaging-stub-triggering]] -==== Stub triggering +=== Stub triggering To trigger a message, use the `StubTrigger` interface, as the following example shows: @@ -214,7 +215,7 @@ or the other in your tests. * <> [[features-messaging-trigger-label]] -==== Trigger by Label +=== Trigger by Label The following example shows how to trigger a message with a label: @@ -226,7 +227,7 @@ include::{tests_path}/spring-cloud-contract-stub-runner-stream/src/test/groovy/o ==== [[features-messaging-trigger-group-artifact-ids]] -==== Trigger by Group and Artifact IDs +=== Trigger by Group and Artifact IDs The following example shows how to trigger a message by group and artifact IDs: @@ -238,7 +239,7 @@ include::{tests_path}/spring-cloud-contract-stub-runner-stream/src/test/groovy/o ==== [[features-messaging-trigger-artifact-ids]] -==== Trigger by Artifact IDs +=== Trigger by Artifact IDs The following example shows how to trigger a message from artifact IDs: @@ -248,7 +249,7 @@ include::{tests_path}/spring-cloud-contract-stub-runner-stream/src/test/groovy/o ---- [[features-messaging-trigger-all-messages]] -==== Trigger All Messages +=== Trigger All Messages The following example shows how to trigger all messages: @@ -261,25 +262,25 @@ include::{tests_path}/spring-cloud-contract-stub-runner-stream/src/test/groovy/o :output_name: jms:output [[features-messaging-stub-runner-camel]] -=== Consumer Side Messaging With Apache Camel +== Consumer Side Messaging With Apache Camel Spring Cloud Contract Stub Runner's messaging module gives you an easy way to integrate with Apache Camel. For the provided artifacts, it automatically downloads the stubs and registers the required routes. [[features-messaging-stub-runner-camel-adding]] -==== Adding Apache Camel to the Project +=== Adding Apache Camel to the Project You can have both Apache Camel and Spring Cloud Contract Stub Runner on the classpath. Remember to annotate your test class with `@AutoConfigureStubRunner`. [[features-messaging-stub-runner-camel-disabling]] -==== Disabling the Functionality +=== Disabling the Functionality If you need to disable this functionality, set the `stubrunner.camel.enabled=false` property. [[features-messaging-stub-runner-camel-example]] -==== Examples +=== Examples Assume that we have the following Maven repository with deployed stubs for the `camelService` application: @@ -340,26 +341,26 @@ That will send out a message to the destination described in the output message :output_name: output [[features-messaging-stub-runner-integration]] -=== Consumer Side Messaging with Spring Integration +== Consumer Side Messaging with Spring Integration Spring Cloud Contract Stub Runner's messaging module gives you an easy way to integrate with Spring Integration. For the provided artifacts, it automatically downloads the stubs and registers the required routes. [[features-messaging-stub-runner-integration-adding]] -==== Adding the Runner to the Project +=== Adding the Runner to the Project You can have both Spring Integration and Spring Cloud Contract Stub Runner on the classpath. Remember to annotate your test class with `@AutoConfigureStubRunner`. [[features-messaging-stub-runner-integration-disabling]] -==== Disabling the Functionality +=== Disabling the Functionality If you need to disable this functionality, set the `stubrunner.integration.enabled=false` property. [[features-messaging-stub-runner-integration-example]] -==== Examples +=== Examples Assume that you have the following Maven repository with deployed stubs for the `integrationService` application: @@ -427,7 +428,7 @@ include::{tests_path}/spring-cloud-contract-stub-runner-integration/src/test/gro That will send out a message to the destination described in the output message of the contract. [[features-messaging-stub-runner-stream]] -=== Consumer Side Messaging With Spring Cloud Stream +== Consumer Side Messaging With Spring Cloud Stream Spring Cloud Contract Stub Runner's messaging module gives you an easy way to integrate with Spring Stream. For the provided artifacts, it automatically downloads the @@ -462,19 +463,19 @@ testImplementation('org.springframework.cloud:spring-cloud-stream-test-binder') ===== [[features-messaging-stub-runner-stream-adding]] -==== Adding the Runner to the Project +=== Adding the Runner to the Project You can have both Spring Cloud Stream and Spring Cloud Contract Stub Runner on the classpath. Remember to annotate your test class with `@AutoConfigureStubRunner`. [[features-messaging-stub-runner-stream-disabling]] -==== Disabling the Functionality +=== Disabling the Functionality If you need to disable this functionality, set the `stubrunner.stream.enabled=false` property. [[features-messaging-stub-runner-stream-example]] -==== Examples +=== Examples Assume that you have the following Maven repository with deployed stubs for the `streamService` application: @@ -552,7 +553,7 @@ include::{tests_path}/spring-cloud-contract-stub-runner-stream/src/test/groovy/o That will send out a message to the destination described in the output message of the contract. [[features-messaging-stub-runner-jms]] -=== Consumer Side Messaging With Spring JMS +== Consumer Side Messaging With Spring JMS Spring Cloud Contract Stub Runner's messaging module provides an easy way to integrate with Spring JMS. @@ -560,7 +561,7 @@ integrate with Spring JMS. The integration assumes that you have a running instance of a JMS broker. [[features-messaging-stub-runner-jms-adding]] -==== Adding the Runner to the Project +=== Adding the Runner to the Project You need to have both Spring JMS and Spring Cloud Contract Stub Runner on the classpath. Remember to annotate your test class with `@AutoConfigureStubRunner`. @@ -569,7 +570,7 @@ with `@AutoConfigureStubRunner`. :output_name: output [[features-messaging-stub-runner-jms-example]] -==== Examples +=== Examples Assume that the stub structure looks as follows: diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner.adoc index 4b3e51e941..9f18282f08 100644 --- a/docs/modules/ROOT/pages/_project-features-stubrunner.adoc +++ b/docs/modules/ROOT/pages/_project-features-stubrunner.adoc @@ -1,5 +1,5 @@ [[features-stub-runner]] -== Spring Cloud Contract Stub Runner += Spring Cloud Contract Stub Runner One of the issues that you might encounter while using Spring Cloud Contract Verifier is passing the generated WireMock JSON stubs from the server side to the client side (or to @@ -10,7 +10,7 @@ question. That is why we introduced Spring Cloud Contract Stub Runner. It can automatically download and run the stubs for you. [[features-stub-runner-snapshot-versions]] -=== Snapshot Versions +== Snapshot Versions You can add the additional snapshot repository to your build file to use snapshot versions, which are automatically uploaded after every successful build, as follows: @@ -30,7 +30,7 @@ include::{standalone_samples_path}/http-server/settings.gradle[tags=repos,indent ==== [[features-stub-runner-publishing-stubs-as-jars]] -=== Publishing Stubs as JARs +== Publishing Stubs as JARs The easiest approach to publishing stubs as jars is to centralize the way stubs are kept. For example, you can keep them as jars in a Maven repository. @@ -62,7 +62,7 @@ include::{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/f ==== [[features-stub-runner-core]] -=== Stub Runner Core +== Stub Runner Core The stub runner core runs stubs for service collaborators. Treating stubs as contracts of services lets you use stub-runner as an implementation of @@ -73,7 +73,7 @@ pick those from the classpath), start WireMock servers for them, and feed them w stub definitions. For messaging, special stub routes are defined. [[features-stub-runner-retrieving]] -==== Retrieving stubs +=== Retrieving stubs You can pick from the following options of acquiring stubs: @@ -84,7 +84,7 @@ You can pick from the following options of acquiring stubs: The latter example is described in the <> section. [[features-stub-runner-downloading-stub]] -===== Downloading Stubs +==== Downloading Stubs You can control the downloading of stubs with the `stubsMode` switch. It picks value from the `StubRunnerProperties.StubsMode` enumeration. You can use the following options: @@ -103,7 +103,7 @@ The following example picks stubs from a local location: ==== [[features-stub-runner-classpath-scanning]] -===== Classpath scanning +==== Classpath scanning If you set the `stubsMode` property to `StubRunnerProperties.StubsMode.CLASSPATH` (or set nothing since `CLASSPATH` is the default value), the classpath is scanned. @@ -222,7 +222,7 @@ By maintaining this structure, the classpath gets scanned and you can profit fro HTTP stubs without the need to download artifacts. [[features-stub-runner-configuring-http-server-stubs]] -===== Configuring HTTP Server Stubs +==== Configuring HTTP Server Stubs Stub Runner has a notion of a `HttpServerStub` that abstracts the underlying concrete implementation of the HTTP server (for example, WireMock is one of the implementations). @@ -262,7 +262,7 @@ include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contra Whenever an HTTPS port is found, it takes precedence over the HTTP port. [[features-stub-runner-running-stubs]] -==== Running stubs +=== Running stubs This section describes how to run stubs. It contains the following topics: @@ -271,7 +271,7 @@ This section describes how to run stubs. It contains the following topics: * <> [[features-stub-runner-http-stubs]] -===== HTTP Stubs +==== HTTP Stubs Stubs are defined in JSON documents, whose syntax is defined in the http://wiremock.org/stubbing.html[WireMock documentation]. @@ -297,7 +297,7 @@ The following example defines a stub in JSON: ==== [[features-stub-runner-viewing]] -===== Viewing Registered Mappings +==== Viewing Registered Mappings Every stubbed collaborator exposes a list of defined mappings under the `__/admin/` endpoint. @@ -361,12 +361,12 @@ the mappings available for the given server: ==== [[features-stub-runner-messaging]] -===== Messaging Stubs +==== Messaging Stubs Depending on the provided Stub Runner dependency and the DSL, the messaging routes are automatically set up. [[features-stub-runner-junit]] -=== Stub Runner JUnit Rule and Stub Runner JUnit5 Extension +== Stub Runner JUnit Rule and Stub Runner JUnit5 Extension Stub Runner comes with a JUnit rule that lets you can download and run stubs for a given group and artifact ID, as the following example shows: @@ -434,21 +434,21 @@ IMPORTANT: To use the JUnit rule or JUnit 5 extension together with messaging, y If you do not do this, then, whenever you try to send a message, an exception is thrown. [[features-stub-runner-rule-maven-settings]] -==== Maven Settings +=== Maven Settings The stub downloader honors Maven settings for a different local repository folder. Authentication details for repositories and profiles are currently not taken into account, so you need to specify it by using the properties mentioned above. [[features-stub-runner-rule-fixed-ports]] -==== Providing Fixed Ports +=== Providing Fixed Ports You can also run your stubs on fixed ports. You can do it in two different ways. One is to pass it in the properties, and the other is to use the fluent API of JUnit rule. [[features-stub-runner-rule-fluent-api]] -==== Fluent API +=== Fluent API When using the `StubRunnerRule` or `StubRunnerExtension`, you can add a stub to download and then pass the port for the last downloaded stub. The following example shows how to do so: @@ -470,7 +470,7 @@ include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contra ==== [[features-stub-runner-rule-spring]] -==== Stub Runner with Spring +=== Stub Runner with Spring Stub Runner with Spring sets up Spring configuration of the Stub Runner project. @@ -533,7 +533,7 @@ int thing2Port; ==== [[features-stub-runner-cloud]] -=== Stub Runner Spring Cloud +== Stub Runner Spring Cloud Stub Runner can integrate with Spring Cloud. @@ -543,7 +543,7 @@ For real life examples, see: - https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/consumer_with_discovery[The consumer application sample] [[features-stub-runner-cloud-stubbing-discovery]] -==== Stubbing Service Discovery +=== Stubbing Service Discovery The most important feature of `Stub Runner Spring Cloud` is the fact that it stubs: @@ -557,7 +557,7 @@ balanced `RestTemplate` or `DiscoveryClient` directly, to call those stubbed ser instead of calling the real Service Discovery tool. [[features-stub-runner-cloud-stubbing-profiles]] -===== Test Profiles and Service Discovery +==== Test Profiles and Service Discovery In your integration tests, you typically do not want to call either a discovery service (such as Eureka) or Config Server. That is why you create an additional test configuration in which you want to disable @@ -579,7 +579,7 @@ in a static block such as the following example (for Eureka): ==== [[features-stub-runner-additional-config]] -==== Additional Configuration +=== Additional Configuration You can match the `artifactId` of the stub with the name of your application by using the `stubrunner.idsToServiceIds:` map. @@ -596,13 +596,13 @@ by setting the following system properties or by setting the corresponding envir - `org.apache.maven.global-settings`: Path to maven global settings location [[features-stub-runner-boot]] -=== Using the Stub Runner Boot Application +== Using the Stub Runner Boot Application Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to trigger the messaging labels and to access WireMock servers. [[features-stub-runner-boot-security]] -==== Stub Runner Boot Security +=== Stub Runner Boot Security The Stub Runner Boot application is not secured by design - securing it would require to add security to all stubs even if they don't actually require it. Since this is a testing utility - the server is **not intended** @@ -612,7 +612,7 @@ IMPORTANT: It is expected that **only a trusted client** has access to the Stub run this application as a Fat Jar or a link:docker-project.html#docker-stubrunner[Docker Image] in untrusted locations. [[features-stub-runner-boot-server]] -==== Stub Runner Server +=== Stub Runner Server To use the Stub Runner Server, add the following dependency: @@ -628,7 +628,7 @@ Then annotate a class with `@EnableStubRunnerServer`, build a fat jar, and it is For the properties, see the <> section. [[features-stub-runner-boot-how-fat-jar]] -==== Stub Runner Server Fat Jar +=== Stub Runner Server Fat Jar You can download a standalone JAR from Maven (for example, for version 2.0.1.RELEASE) by running the following commands: @@ -642,7 +642,7 @@ $ java -jar stub-runner.jar --stubrunner.ids=... --stubrunner.repositoryRoot=... ==== [[features-stub-runner-boot-how-cli]] -==== Spring Cloud CLI +=== Spring Cloud CLI Starting from the `1.4.0.RELEASE` version of the https://cloud.spring.io/spring-cloud-cli[Spring Cloud CLI] project, you can start Stub Runner Boot by running `spring cloud stubrunner`. @@ -667,7 +667,7 @@ Then you can call `spring cloud stubrunner` from your terminal window to start the Stub Runner server. It is available at port `8750`. [[features-stub-runner-boot-endpoints]] -==== Endpoints +=== Endpoints Stub Runner Boot offers two endpoints: @@ -675,7 +675,7 @@ Stub Runner Boot offers two endpoints: * <> [[features-stub-runner-boot-endpoints-http]] -===== HTTP +==== HTTP For HTTP, Stub Runner Boot makes the following endpoints available: @@ -683,7 +683,7 @@ For HTTP, Stub Runner Boot makes the following endpoints available: - GET `/stubs/{ivy}`: Returns a port for the given `ivy` notation (when calling the endpoint `ivy` can also be `artifactId` only) [[features-stub-runner-boot-endpoints-messaging]] -===== Messaging +==== Messaging For Messaging, Stub Runner Boot makes the following endpoints available: @@ -693,7 +693,7 @@ For Messaging, Stub Runner Boot makes the following endpoints available: (when calling the endpoint, `ivy` can also be `artifactId` only) [[features-stub-runner-boot-endpoints-example]] -==== Example +=== Example The following example shows typical usage of Stub Runner Boot: @@ -703,7 +703,7 @@ include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contra ---- [[features-stub-runner-boot-service-discovery]] -==== Stub Runner Boot with Service Discovery +=== Stub Runner Boot with Service Discovery One way to use Stub Runner Boot is to use it as a feed of stubs for "`smoke tests`". What does that mean? Assume that you do not want to deploy 50 microservices to a test environment in order @@ -727,7 +727,7 @@ likely to change. That way, you can provide only the list of stubs to download w the Stub Runner Boot. [[features-stub-runner-stubs-per-consumer]] -=== Consumer-Driven Contracts: Stubs Per Consumer +== Consumer-Driven Contracts: Stubs Per Consumer There are cases in which two consumers of the same endpoint want to have two different responses. @@ -825,7 +825,7 @@ For more information about the reasons behind this change, see https://github.com/spring-cloud/spring-cloud-contract/issues/224[issue 224]. [[features-stub-runner-stubs-protocol]] -=== Fetching Stubs or Contract Definitions From A Location +== Fetching Stubs or Contract Definitions From A Location Instead of picking the stubs or contract definitions from Artifactory, Nexus, or Git, you can point to @@ -946,7 +946,7 @@ stubsMode = StubRunnerProperties.StubsMode.REMOTE, ==== [[features-stub-runner-generate-stubs-at-runtime]] -=== Generating Stubs at Runtime +== Generating Stubs at Runtime As a consumer, you might not want to wait for the producer to finish its implementation and then publish their stubs. A solution to this problem can be generation of stubs at runtime. @@ -989,7 +989,7 @@ stubsMode = StubRunnerProperties.StubsMode.REMOTE, ==== [[features-stub-runner-fail-on-no-stubs]] -=== Fail On No Stubs +== Fail On No Stubs By default, Stub Runner will fail if no stubs are found. In order to change that behavior, set the `failOnNoStubs` property to `false` in the annotation or call the `withFailOnNoStubs(false)` method on a JUnit Rule or Extension. The following example shows how to do so: @@ -1028,7 +1028,7 @@ stubsMode = StubRunnerProperties.StubsMode.REMOTE, ==== [[features-stub-runner-common]] -=== Common Properties +== Common Properties This section briefly describes common properties, including: @@ -1036,7 +1036,7 @@ This section briefly describes common properties, including: * <> [[features-stub-runner-common-properties-junit-spring]] -==== Common Properties for JUnit and Spring +=== Common Properties for JUnit and Spring You can set repetitive properties by using system properties or Spring configuration properties. The following table shows their names with their default values: @@ -1061,7 +1061,7 @@ override the consumer name, change this value. |=============== [[features-stub-runner-stub-runner-stub-ids]] -==== Stub Runner Stubs IDs +=== Stub Runner Stubs IDs You can set the stubs to download in the `stubrunner.ids` system property. They use the following pattern: diff --git a/docs/modules/ROOT/pages/_project-features-wiremock.adoc b/docs/modules/ROOT/pages/_project-features-wiremock.adoc index 5b5ee8e19a..acfc3be053 100644 --- a/docs/modules/ROOT/pages/_project-features-wiremock.adoc +++ b/docs/modules/ROOT/pages/_project-features-wiremock.adoc @@ -1,5 +1,6 @@ [[features-wiremock]] -== Spring Cloud Contract WireMock += Spring Cloud Contract WireMock + include::_attributes.adoc[] The Spring Cloud Contract WireMock modules let you use https://github.com/tomakehurst/wiremock[WireMock] in a @@ -32,7 +33,7 @@ The registered WireMock server is reset after each test class. However, if you need to reset it after each test method, set the `wiremock.reset-mappings-after-each-test` property to `true`. [[features-wiremock-registering-stubs]] -=== Registering Stubs Automatically +== Registering Stubs Automatically If you use `@AutoConfigureWireMock`, it registers WireMock JSON stubs from the file system or classpath (by default, from `file:src/test/resources/mappings`). You can @@ -82,7 +83,7 @@ include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wirem ==== [[features-wiremock-using-files]] -=== Using Files to Specify the Stub Bodies +== Using Files to Specify the Stub Bodies WireMock can read response bodies from files on the classpath or the file system. In the case of the file system, you can see in the JSON DSL that the response has a `bodyFileName` instead of a @@ -102,7 +103,7 @@ NOTE: The value of `files` has no effect on the stubs loaded explicitly from the `stubs` attribute. [[features-wiremock-junit-rule]] -=== Alternative: Using JUnit Rules +== Alternative: Using JUnit Rules For a more conventional WireMock experience, you can use JUnit `@Rules` to start and stop the server. To do so, use the `WireMockSpring` convenience class to obtain an `Options` @@ -120,7 +121,7 @@ The `@ClassRule` means that the server shuts down after all the methods in this have been run. [[features-wiremock-relaxed-ssl]] -=== Relaxed SSL Validation for Rest Template +== Relaxed SSL Validation for Rest Template WireMock lets you stub a "`secure`" server with an `https` URL protocol. If your application wants to contact that stub server in an integration test, it finds that @@ -174,7 +175,7 @@ To disable the custom `RestTemplateBuilder`, set the `wiremock.rest-template-ssl property to `false`. [[features-wiremock-spring-mvc-mocks]] -=== WireMock and Spring MVC Mocks +== WireMock and Spring MVC Mocks Spring Cloud Contract provides a convenience class that can load JSON WireMock stubs into a Spring `MockRestServiceServer`. The following code shows an example: diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc index eaa5d7f709..95f630cbb3 100644 --- a/docs/modules/ROOT/pages/appendix.adoc +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -1,7 +1,7 @@ :numbered!: [appendix] [[common-application-properties]] -== Common application properties += Common application properties include::_attributes.adoc[] @@ -12,11 +12,11 @@ NOTE: Property contributions can come from additional jar files on your classpat Also, you can define your own properties. [[default-application-properties]] -=== Default application properties +== Default application properties include::_configprops.adoc[] [[additional-application-properties]] -=== Additional application properties +== Additional application properties include::_additional-stubrunner-configprops.adoc[] diff --git a/docs/modules/ROOT/pages/sagan-boot.adoc b/docs/modules/ROOT/pages/sagan-boot.adoc index aeffe8949f..b42debcca8 100644 --- a/docs/modules/ROOT/pages/sagan-boot.adoc +++ b/docs/modules/ROOT/pages/sagan-boot.adoc @@ -1,5 +1,5 @@ [[on-the-producer-side]] -== On the Producer Side += On the Producer Side To start working with Spring Cloud Contract, you can add files with REST or 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. @@ -57,7 +57,7 @@ INFO: The baseClassForTests element lets you specify your base test class. It mu Once the implementation and the test base class are in place, the tests pass, and both the application and the stub artifacts are built and installed in the local Maven repository. You can now merge the changes, and you can publish both the application and the stub artifacts in an online repository. [[on-the-consumer-side]] -== On the Consumer Side += On the Consumer Side You can use Spring Cloud Contract Stub Runner in the integration tests to get a running WireMock instance or messaging route that simulates the actual service. diff --git a/docs/modules/ROOT/pages/yml-schema.adoc b/docs/modules/ROOT/pages/yml-schema.adoc index ec32d4543d..eef8059bf3 100644 --- a/docs/modules/ROOT/pages/yml-schema.adoc +++ b/docs/modules/ROOT/pages/yml-schema.adoc @@ -1,5 +1,6 @@ [[yml-schema]] -== YML Schema += YML Schema + include::_attributes.adoc[] Below you can find a JSON schema definition of a YAML contract.