Fix cross references
This commit is contained in:
Marcin Grzejszczak
@@ -9,9 +9,9 @@ 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}, 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>> :: Contract DSL, Messaging, Spring Cloud Contract Stub Runner, and Spring Cloud Contract WireMock.
|
||||
<<project-features.adoc#features-build-tools,Build Tools>> :: Maven Plugin, Gradle Plugin, and Docker.
|
||||
<<howto.adoc#howto,"`How-to`" Guides>> :: Stubs versioning, Debugging, and more.
|
||||
xref:getting-started.adoc[Getting Started] :: Introducing {project-full-name}, Developing Your First {project-full-name}-based Application
|
||||
xref:using.adoc[Using {project-full-name}] :: {project-full-name} usage examples and workflows.
|
||||
xref:project-features.adoc[{project-full-name} Features] :: Contract DSL, Messaging, Spring Cloud Contract Stub Runner, and Spring Cloud Contract WireMock.
|
||||
xref:project-features.adoc#features-build-tools[Build Tools] :: Maven Plugin, Gradle Plugin, and Docker.
|
||||
xref:howto.adoc["`How-to`" Guides] :: Stubs versioning, Debugging, and more.
|
||||
<<appendix.adoc#appendix,Appendices>> :: Properties, Metadata, Configuration, Dependencies, and more.
|
||||
|
||||
@@ -3,12 +3,12 @@
|
||||
|
||||
The following sections describe the most common top-level elements:
|
||||
|
||||
* <<contract-dsl-description>>
|
||||
* <<contract-dsl-name>>
|
||||
* <<contract-dsl-ignoring-contracts>>
|
||||
* <<contract-dsl-in-progress>>
|
||||
* <<contract-dsl-passing-values-from-files>>
|
||||
* <<contract-dsl-metadata>>
|
||||
* xref:_project-features-contract/common-top-elements.adoc#contract-dsl-description[Description]
|
||||
* xref:_project-features-contract/common-top-elements.adoc#contract-dsl-name[Name]
|
||||
* xref:_project-features-contract/common-top-elements.adoc#contract-dsl-ignoring-contracts[Ignoring Contracts]
|
||||
* xref:_project-features-contract/common-top-elements.adoc#contract-dsl-in-progress[Contracts in Progress]
|
||||
* xref:_project-features-contract/common-top-elements.adoc#contract-dsl-passing-values-from-files[Passing Values from Files]
|
||||
* xref:_project-features-contract/common-top-elements.adoc#contract-dsl-metadata[Metadata]
|
||||
|
||||
[[contract-dsl-description]]
|
||||
== Description
|
||||
|
||||
@@ -20,7 +20,7 @@ IMPORTANT: Entries inside the `matchers` must reference existing elements of the
|
||||
== Dynamic Properties inside the Body
|
||||
|
||||
IMPORTANT: This section is valid only for the Coded DSL (Groovy, Java, and so on). See the
|
||||
<<contract-dsl-matchers>> section for YAML examples of a similar feature.
|
||||
xref:_project-features-contract/dsl-dynamic-properties.adoc#contract-dsl-matchers[Dynamic Properties in the Matchers Sections] section for YAML examples of a similar feature.
|
||||
|
||||
You can set the properties inside the body either with the `value` method or, if you use
|
||||
the Groovy map notation, with `$()`. The following example shows how to set dynamic
|
||||
@@ -53,7 +53,7 @@ method. Subsequent sections take a closer look at what you can do with those val
|
||||
== Regular Expressions
|
||||
|
||||
IMPORTANT: This section is valid only for the Groovy DSL. See the
|
||||
<<contract-dsl-matchers>> section for YAML examples of a similar feature.
|
||||
xref:_project-features-contract/dsl-dynamic-properties.adoc#contract-dsl-matchers[Dynamic Properties in the Matchers Sections] section for YAML examples of a similar feature.
|
||||
|
||||
You can use regular expressions to write your requests in the contract DSL. Doing so is
|
||||
particularly useful when you want to indicate that a given response should be provided
|
||||
@@ -63,7 +63,7 @@ need to use patterns and not exact values both for your tests and your server-si
|
||||
Make sure that regex matches a whole region of a sequence, as, internally,
|
||||
https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#matches[`Pattern.matches()`]
|
||||
is called. For instance, `abc` does not match `aabc`, but `.abc` does.
|
||||
There are several additional <<contract-dsl-regex-limitations,known limitations>> as well.
|
||||
There are several additional xref:_project-features-contract/dsl-dynamic-properties.adoc#contract-dsl-regex-limitations[known limitations] as well.
|
||||
|
||||
The following example shows how to use regular expressions to write a request:
|
||||
|
||||
@@ -154,7 +154,7 @@ See https://github.com/spring-cloud/spring-cloud-contract/issues/900[Issue 900].
|
||||
== Passing Optional Parameters
|
||||
|
||||
IMPORTANT: This section is valid only for Groovy DSL. See the
|
||||
<<contract-dsl-matchers>> section for YAML examples of a similar feature.
|
||||
xref:_project-features-contract/dsl-dynamic-properties.adoc#contract-dsl-matchers[Dynamic Properties in the Matchers Sections] section for YAML examples of a similar feature.
|
||||
|
||||
You can provide optional parameters in your contract. However, you can provide
|
||||
optional parameters only for the following:
|
||||
@@ -208,7 +208,7 @@ include:../:{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/
|
||||
== Calling Custom Methods on the Server Side
|
||||
|
||||
IMPORTANT: This section is valid only for the Groovy DSL. See the
|
||||
<<contract-dsl-matchers>> section for YAML examples of a similar feature.
|
||||
xref:_project-features-contract/dsl-dynamic-properties.adoc#contract-dsl-matchers[Dynamic Properties in the Matchers Sections] section for YAML examples of a similar feature.
|
||||
|
||||
You can define a method call that runs on the server side during the test. Such a
|
||||
method can be added to the class defined as `baseClassForTests` in the configuration. The
|
||||
|
||||
@@ -33,7 +33,7 @@ include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_example
|
||||
====
|
||||
|
||||
Besides status, the response may contain headers, cookies, and a body, which are
|
||||
specified the same way as in the request (see <<contract-dsl-request>>).
|
||||
specified the same way as in the request (see xref:_project-features-contract/dsl-request.adoc[HTTP Request]).
|
||||
|
||||
TIP: In the Groovy DSL, you can reference the `org.springframework.cloud.contract.spec.internal.HttpStatus`
|
||||
methods to provide a meaningful status instead of a digit. For example, you can call
|
||||
|
||||
@@ -177,7 +177,7 @@ methods to create request matchers, but you cannot use both approaches.
|
||||
|
||||
On the consumer side, you can make the `resource.json` generated earlier in this section
|
||||
available on the classpath (by
|
||||
<<features-stub-runner-publishing-stubs-as-jars>>, for example). After that, you can create a stub that uses WireMock in a
|
||||
xref:_project-features-stubrunner/stub-runner-publishing-stubs-as-jars.adoc[Publishing Stubs as JARs], for example). After that, you can create a stub that uses WireMock in a
|
||||
number of different ways, including by using
|
||||
`@AutoConfigureWireMock(stubs="classpath:resource.json")`, as described earlier in this
|
||||
document.
|
||||
@@ -254,7 +254,7 @@ contract. The location of this file would be `index/dsl-contract.adoc`.
|
||||
|
||||
The method `SpringCloudContractRestDocs.dslContract()` takes an optional Map parameter that allows you to specify additional attributes in the template.
|
||||
|
||||
One of these attributes is the <<contract-dsl-http-top-level-elements,priority>> field that you may specify as follows:
|
||||
One of these attributes is the xref:_project-features-contract/dsl-http-top-level-elements.adoc[priority] field that you may specify as follows:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
||||
@@ -12,9 +12,9 @@ but you can also create one of your own and use that.
|
||||
The DSL for messaging looks a little bit different than the one that focuses on HTTP. The
|
||||
following sections explain the differences:
|
||||
|
||||
* <<contract-dsl-output-triggered-method>>
|
||||
* <<contract-dsl-consumer-producer>>
|
||||
* <<contract-dsl-messaging-common>>
|
||||
* xref:_project-features-messaging.adoc#contract-dsl-output-triggered-method[Output Triggered by a Method]
|
||||
* xref:_project-features-messaging.adoc#contract-dsl-consumer-producer[Consumer/Producer]
|
||||
* xref:_project-features-messaging.adoc#contract-dsl-messaging-common[Common]
|
||||
|
||||
[[contract-dsl-output-triggered-method]]
|
||||
=== Output Triggered by a Method
|
||||
@@ -208,10 +208,10 @@ or the other in your tests.
|
||||
|
||||
`StubTrigger` gives you the following options to trigger a message:
|
||||
|
||||
* <<features-messaging-trigger-label>>
|
||||
* <<features-messaging-trigger-group-artifact-ids>>
|
||||
* <<features-messaging-trigger-artifact-ids>>
|
||||
* <<features-messaging-trigger-all-messages>>
|
||||
* xref:_project-features-messaging.adoc#features-messaging-trigger-label[Trigger by Label]
|
||||
* xref:_project-features-messaging.adoc#features-messaging-trigger-group-artifact-ids[Trigger by Group and Artifact IDs]
|
||||
* xref:_project-features-messaging.adoc#features-messaging-trigger-artifact-ids[Trigger by Artifact IDs]
|
||||
* xref:_project-features-messaging.adoc#features-messaging-trigger-all-messages[Trigger All Messages]
|
||||
|
||||
[[features-messaging-trigger-label]]
|
||||
=== Trigger by Label
|
||||
|
||||
@@ -28,7 +28,7 @@ compile "org.springframework.cloud:spring-cloud-starter-stub-runner"
|
||||
|
||||
Then annotate a class with `@EnableStubRunnerServer`, build a fat jar, and it is ready to work.
|
||||
|
||||
For the properties, see the <<features-stub-runner-rule-spring,Stub Runner Spring>> section.
|
||||
For the properties, see the xref:_project-features-stubrunner/stub-runner-junit.adoc#features-stub-runner-rule-spring[Stub Runner Spring] section.
|
||||
|
||||
[[features-stub-runner-boot-how-fat-jar]]
|
||||
== Stub Runner Server Fat Jar
|
||||
@@ -74,8 +74,8 @@ the Stub Runner server. It is available at port `8750`.
|
||||
|
||||
Stub Runner Boot offers two endpoints:
|
||||
|
||||
* <<features-stub-runner-boot-endpoints-http>>
|
||||
* <<features-stub-runner-boot-endpoints-messaging>>
|
||||
* xref:_project-features-stubrunner/stub-runner-boot.adoc#features-stub-runner-boot-endpoints-http[HTTP]
|
||||
* xref:_project-features-stubrunner/stub-runner-boot.adoc#features-stub-runner-boot-endpoints-messaging[Messaging]
|
||||
|
||||
[[features-stub-runner-boot-endpoints-http]]
|
||||
=== HTTP
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
|
||||
This section briefly describes common properties, including:
|
||||
|
||||
* <<features-stub-runner-common-properties-junit-spring>>
|
||||
* <<features-stub-runner-stub-runner-stub-ids>>
|
||||
* xref:_project-features-stubrunner/stub-runner-common.adoc#features-stub-runner-common-properties-junit-spring[Common Properties for JUnit and Spring]
|
||||
* xref:_project-features-stubrunner/stub-runner-common.adoc#features-stub-runner-stub-runner-stub-ids[Stub Runner Stubs IDs]
|
||||
|
||||
[[features-stub-runner-common-properties-junit-spring]]
|
||||
== Common Properties for JUnit and Spring
|
||||
|
||||
@@ -18,7 +18,7 @@ You can pick from the following options of acquiring stubs:
|
||||
- Classpath-scanning solution that searches the classpath with a pattern to retrieve stubs
|
||||
- Writing your own implementation of the `org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder` for full customization
|
||||
|
||||
The latter example is described in the <<advanced.html#customization-custom-stub-runner, Custom Stub Runner>> section.
|
||||
The latter example is described in the xref:advanced.adoc#customization-custom-stub-runner[Custom Stub Runner] section.
|
||||
|
||||
[[features-stub-runner-downloading-stub]]
|
||||
=== Downloading Stubs
|
||||
@@ -203,9 +203,9 @@ Whenever an HTTPS port is found, it takes precedence over the HTTP port.
|
||||
|
||||
This section describes how to run stubs. It contains the following topics:
|
||||
|
||||
* <<features-stub-runner-http-stubs>>
|
||||
* <<features-stub-runner-viewing>>
|
||||
* <<features-stub-runner-messaging>>
|
||||
* xref:_project-features-stubrunner/stub-runner-core.adoc#features-stub-runner-http-stubs[HTTP Stubs]
|
||||
* xref:_project-features-stubrunner/stub-runner-core.adoc#features-stub-runner-viewing[Viewing Registered Mappings]
|
||||
* xref:_project-features-stubrunner/stub-runner-core.adoc#features-stub-runner-messaging[Messaging Stubs]
|
||||
|
||||
[[features-stub-runner-http-stubs]]
|
||||
=== HTTP Stubs
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
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.
|
||||
|
||||
As a producer, when a contract is defined, you are required to make the generated tests pass in order for the stubs to be published. There are cases where you would like to unblock the consumers so that they can fetch the stubs before your tests actually pass. In this case, you should set such contracts as in-progress. You can read more about this under the <<contract-dsl-in-progress>> section. That way, your tests are not generated, but the stubs are generated.
|
||||
As a producer, when a contract is defined, you are required to make the generated tests pass in order for the stubs to be published. There are cases where you would like to unblock the consumers so that they can fetch the stubs before your tests actually pass. In this case, you should set such contracts as in-progress. You can read more about this under the xref:_project-features-contract/common-top-elements.adoc#contract-dsl-in-progress[Contracts in Progress] section. That way, your tests are not generated, but the stubs are generated.
|
||||
|
||||
As a consumer, you can toggle a switch to generate stubs at runtime. Stub Runner ignores all the existing stub mappings and generates new ones for all the contract definitions. Another option is to pass the `stubrunner.generate-stubs` system property. The following example shows such a setup:
|
||||
|
||||
|
||||
@@ -59,7 +59,7 @@ include:../:{stubrunner_core_path}/src/test/java/org/springframework/cloud/contr
|
||||
----
|
||||
====
|
||||
|
||||
See the <<features-stub-runner-common-properties-junit-spring>> for more information on
|
||||
See the xref:_project-features-stubrunner/stub-runner-common.adoc#features-stub-runner-common-properties-junit-spring[Common Properties for JUnit and 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
|
||||
|
||||
@@ -61,7 +61,7 @@ public class WiremockImportApplicationTests {
|
||||
|
||||
NOTE: Actually, WireMock always loads mappings from `src/test/resources/mappings` *as
|
||||
well as* the custom locations in the `stubs` attribute. To change this behavior, you can
|
||||
also specify a file root, as described in the <<features-wiremock-using-files,next section of this document>>.
|
||||
also specify a file root, as described in the xref:_project-features-wiremock.adoc#features-wiremock-using-files[next section of this document].
|
||||
|
||||
NOTE: Also, the mappings in the `stubs` location are not considered part of Wiremock's "default mappings" and calls
|
||||
to `com.github.tomakehurst.wiremock.client.WireMock.resetToDefaultMappings` during a test do not result in the mappings
|
||||
|
||||
@@ -398,7 +398,7 @@ Since the Spring Cloud Contract Stub Runner Docker Image uses the standalone ver
|
||||
[[docker-stubrunner-env-vars]]
|
||||
=== Environment Variables
|
||||
|
||||
You can run the docker image and pass any of the <<project-features.adoc#features-stub-runner-common-properties-junit-spring, common properties for JUnit and Spring>>
|
||||
You can run the docker image and pass any of the xref:_project-features-stubrunner/stub-runner-common.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 dot (`.`) should be replaced with underscore (`_`) characters. For example,
|
||||
|
||||
@@ -25,7 +25,7 @@ copy contains this Copyright Notice, whether distributed in print or electronica
|
||||
== Getting Help
|
||||
If you have trouble with {project-full-name}, we would like to help.
|
||||
|
||||
* Try the <<howto.adoc#howto, How-to documents>>. They provide solutions to the most
|
||||
* Try the xref:howto.adoc[How-to documents]. They provide solutions to the most
|
||||
common questions.
|
||||
* Learn the {project-full-name} basics. If you are
|
||||
starting out with {project-full-name}, try one of the https://spring.io/guides[guides].
|
||||
@@ -42,37 +42,37 @@ involved].
|
||||
[[contract-documentation-first-steps]]
|
||||
== First Steps
|
||||
If you are getting started with {project-full-name} or 'Spring' in general, start with
|
||||
<<getting-started.adoc#getting-started, the following topics>>:
|
||||
xref:getting-started.adoc[the following topics]:
|
||||
|
||||
* *From scratch:*
|
||||
<<getting-started.adoc#getting-started-introducing-{project-name}, Overview>> |
|
||||
<<getting-started.adoc#getting-started-three-second-tour, Three-second Tour>> |
|
||||
<<getting-started.adoc#getting-started-first-application, First application>>
|
||||
xref:getting-started/three-second-tour.adoc[Three-second Tour] |
|
||||
xref:getting-started/first-application.adoc[First application]
|
||||
* *Tutorial:*
|
||||
<<getting-started.adoc#getting-started-cdc, Introduction>> |
|
||||
xref:getting-started/cdc.adoc[Introduction] |
|
||||
<<getting-started.adoc#consumer-side-loan-issuance, Consumer, Part 1>> |
|
||||
<<getting-started.adoc#producer-side-fraud-detection-server, Producer>> |
|
||||
<<getting-started.adoc#consumer-side-loan-issuance-final-step, Consumer, Part 2>>
|
||||
xref:getting-started/cdc.adoc#getting-started-cdc-consumer-final[Consumer, Part 2]
|
||||
|
||||
|
||||
|
||||
[[working-with-{project-full-name}]]
|
||||
== Working with {project-full-name}
|
||||
Ready to actually start using {project-full-name}? <<using.adoc#using, We have
|
||||
you covered>>:
|
||||
Ready to actually start using {project-full-name}? xref:using.adoc[We have you covered]
|
||||
:
|
||||
|
||||
* *Provider contract testing:*
|
||||
|
||||
** <<using.adoc#flows-provider-nexus,Provider contract testing with stubs in Nexus or Artifactory>>
|
||||
** <<using.adoc#flows-provider-git,Provider contract testing with stubs in Git>>
|
||||
** <<using.adoc#flows-provider-non-spring,Provider contract testing with stubs in Artifactory for a non-Spring application>>
|
||||
** <<using.adoc#flows-provider-non-jvm,Provider contract testing with stubs in Artifactory in non JVM world>>
|
||||
** <<using.adoc#flows-provider-rest-docs,Provider contract testing with REST Docs and stubs in Nexus / Artifactory>>
|
||||
** xref:using.adoc#flows-provider-nexus[Provider contract testing with stubs in Nexus or Artifactory]
|
||||
** xref:using.adoc#flows-provider-git[Provider contract testing with stubs in Git]
|
||||
** xref:using.adoc#flows-provider-non-spring[Provider contract testing with stubs in Artifactory for a non-Spring application]
|
||||
** xref:using.adoc#flows-provider-non-jvm[Provider contract testing with stubs in Artifactory in non JVM world]
|
||||
** xref:using.adoc#flows-provider-rest-docs[Provider contract testing with REST Docs and stubs in Nexus / Artifactory]
|
||||
|
||||
* *Consumer-Driven contract testing:*
|
||||
** <<using.adoc#flows-cdc-contracts-producer,Consumer Driven Contracts with contracts on the producer side>>
|
||||
** <<using.adoc#flows-cdc-contracts-external,Consumer Driven Contracts with contracts in external repo>>
|
||||
** <<using.adoc#flows-cdc-contracts-stubs-git,Consumer Driven Contracts with contracts on the producer side, pushed to git>>
|
||||
** xref:using.adoc#flows-cdc-contracts-producer[Consumer Driven Contracts with contracts on the producer side]
|
||||
** xref:using.adoc#flows-cdc-contracts-external[Consumer Driven Contracts with contracts in external repo]
|
||||
** xref:using.adoc#flows-cdc-contracts-stubs-git[Consumer Driven Contracts with contracts on the producer side, pushed to git]
|
||||
|
||||
TIP: We talk about *Provider Contracts* when it is the producer of the API that defines the contracts and
|
||||
publishes it for all its consumers to use. This approach is useful for producers that cannot
|
||||
@@ -87,19 +87,19 @@ of consumers is not extremely large.
|
||||
[[learning-about-{project-full-name}-features]]
|
||||
== Learning about {project-full-name} Features
|
||||
Need more details about {project-full-name}'s core features?
|
||||
<<project-features.adoc#features, The following content is for you>>:
|
||||
xref:project-features.adoc[The following content is for you]:
|
||||
|
||||
* *Core Features:*
|
||||
<<project-features.adoc#contract-dsl, Contract DSL>> |
|
||||
<<project-features.adoc#features-http, Contracts for HTTP>> |
|
||||
<<project-features.adoc#features-messaging, Contracts for Messaging>>
|
||||
xref:_project-features-contract.adoc[Contract DSL] |
|
||||
xref:_project-features-contract/common-top-elements.adoc#features-http[Contracts for HTTP] |
|
||||
xref:_project-features-messaging.adoc[Contracts for Messaging]
|
||||
* *Integrations:*
|
||||
<<project-features.adoc#features-jax-rs, JAX-RS>> |
|
||||
<<project-features.adoc#features-context-paths, Context Paths>> |
|
||||
<<project-features.adoc#features-rest-docs, RESTDocs>>
|
||||
xref:_project-features-flows/jax-rs.adoc[JAX-RS] |
|
||||
xref:_project-features-flows/context-paths.adoc[Context Paths] |
|
||||
xref:_project-features-flows/rest-docs.adoc[RESTDocs]
|
||||
* *Modules:*
|
||||
<<project-features.adoc#features-stub-runner, Stub Runner>> |
|
||||
<<project-features.adoc#features-wiremock, WireMock>>
|
||||
xref:_project-features-stubrunner.adoc[Stub Runner] |
|
||||
xref:_project-features-wiremock.adoc[WireMock]
|
||||
// TODO: links don't work in "build Tools" section
|
||||
* *Build Tools:*
|
||||
link:maven-project.html[Contract Verifier - Maven] |
|
||||
@@ -118,8 +118,8 @@ Finally, we have a few topics for more advanced users:
|
||||
<<advanced.adoc#contract-dsl-plugin-dep, Plugin Dependency>> |
|
||||
<<advanced.adoc#contract-dsl-referencing, Referencing the DSL>>
|
||||
* *Customizing WireMock:*
|
||||
<<advanced.adoc#customization-wiremock-extension, Extensions>> |
|
||||
<<advanced.adoc#customization-wiremock-configuration, Configuration>>
|
||||
xref:advanced.adoc#customization-wiremock-extension[Extensions] |
|
||||
xref:advanced.adoc#customization-wiremock-configuration[Configuration]
|
||||
* *Customizing {project-full-name}:*
|
||||
<<advanced.adoc#contract-dsl-pluggable-architecture, Pluggable Architecture>> |
|
||||
<<advanced.adoc#contract-dsl-custom-contract-converter, Contract Converter>> |
|
||||
|
||||
@@ -3,11 +3,11 @@
|
||||
|
||||
This brief tour walks through using Spring Cloud Contract. It consists of the following topics:
|
||||
|
||||
* <<getting-started-first-application-producer>>
|
||||
* <<getting-started-first-application-consumer>>
|
||||
* xref:getting-started/first-application.adoc#getting-started-first-application-producer[On the Producer Side]
|
||||
* xref:getting-started/first-application.adoc#getting-started-first-application-consumer[On the Consumer Side]
|
||||
|
||||
You can find an even more brief tour
|
||||
<<getting-started-three-second-tour,here>>.
|
||||
xref:getting-started/three-second-tour.adoc[here].
|
||||
|
||||
For the sake of this example, the `Stub Storage` is Nexus/Artifactory.
|
||||
|
||||
|
||||
@@ -4,11 +4,11 @@
|
||||
This very brief tour walks through using Spring Cloud Contract. It consists of the
|
||||
following topics:
|
||||
|
||||
* <<getting-started-three-second-tour-producer>>
|
||||
* <<getting-started-three-second-tour-consumer>>
|
||||
* xref:getting-started/three-second-tour.adoc#getting-started-three-second-tour-producer[On the Producer Side]
|
||||
* xref:getting-started/three-second-tour.adoc#getting-started-three-second-tour-consumer[On the Consumer Side]
|
||||
|
||||
You can find a somewhat longer tour
|
||||
<<getting-started-first-application,here>>.
|
||||
xref:getting-started/first-application.adoc[here].
|
||||
|
||||
The following UML diagram shows the relationship of the parts within Spring Cloud Contract:
|
||||
|
||||
|
||||
@@ -6,9 +6,9 @@ to writing your own applications. If you are a task-oriented type of developer,
|
||||
want to jump over to https://spring.io and check out some
|
||||
https://spring.io/guides/[getting started] guides that solve specific "`How do I do that
|
||||
with Spring?`" problems. We also have {project-full-name}-specific
|
||||
"`<<howto.adoc#howto, how-to>>`" reference documentation.
|
||||
"`xref:howto.adoc[how-to]`" reference documentation.
|
||||
|
||||
Otherwise, the next logical step is to read <<using.adoc#using, Using {project-full-name}>>. If
|
||||
Otherwise, the next logical step is to read xref:using.adoc[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>>.
|
||||
|
||||
|
||||
@@ -4,20 +4,20 @@
|
||||
To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the
|
||||
following sections:
|
||||
|
||||
* <<gradle-prerequisites>>
|
||||
* <<gradle-add-gradle-plugin>>
|
||||
* <<gradle-and-rest-assured>>
|
||||
* <<gradle-snapshot-versions>>
|
||||
* <<gradle-add-stubs>>
|
||||
* <<gradle-default-setup>>
|
||||
* <<gradle-configure-plugin>>
|
||||
* <<gradle-configuration-options>>
|
||||
* <<gradle-single-base-class>>
|
||||
* <<gradle-different-base-classes>>
|
||||
* <<gradle-invoking-generated-tests>>
|
||||
* <<gradle-publishing-stubs-to-artifact-repo>>
|
||||
* <<gradle-pushing-stubs-to-scm>>
|
||||
* <<gradle-consumer>>
|
||||
* xref:gradle-project.adoc#gradle-prerequisites[Prerequisites]
|
||||
* xref:gradle-project.adoc#gradle-add-gradle-plugin[Add Gradle Plugin with Dependencies]
|
||||
* xref:gradle-project.adoc#gradle-and-rest-assured[Gradle and Rest Assured 2.0]
|
||||
* xref:gradle-project.adoc#gradle-snapshot-versions[Snapshot Versions for Gradle]
|
||||
* xref:gradle-project.adoc#gradle-add-stubs[Add stubs]
|
||||
* xref:gradle-project.adoc#gradle-default-setup[Default Setup]
|
||||
* xref:gradle-project.adoc#gradle-configure-plugin[Configuring the Plugin]
|
||||
* xref:gradle-project.adoc#gradle-configuration-options[Configuration Options]
|
||||
* xref:gradle-project.adoc#gradle-single-base-class[Single Base Class for All Tests]
|
||||
* xref:gradle-project.adoc#gradle-different-base-classes[Different Base Classes for Contracts]
|
||||
* xref:gradle-project.adoc#gradle-invoking-generated-tests[Invoking Generated Tests]
|
||||
* xref:gradle-project.adoc#gradle-publishing-stubs-to-artifact-repo[Publishing Stubs to Artifact Repository]
|
||||
* xref:gradle-project.adoc#gradle-pushing-stubs-to-scm[Pushing Stubs to SCM]
|
||||
* xref:gradle-project.adoc#gradle-consumer[Spring Cloud Contract Verifier on the Consumer Side]
|
||||
|
||||
[[gradle-prerequisites]]
|
||||
== Prerequisites
|
||||
@@ -505,7 +505,7 @@ $ ./gradlew pushStubsToScm
|
||||
----
|
||||
====
|
||||
|
||||
Under <<scm-stub-downloader>>, you can find all possible
|
||||
Under xref:advanced.adoc#scm-stub-downloader[Using the SCM Stub Downloader], you can find all possible
|
||||
configuration options that you can pass either through
|
||||
the `contractsProperties` field (for example, `contracts { contractsProperties = [foo:"bar"] }`),
|
||||
through the `contractsProperties` method (for example, `contracts { contractsProperties([foo:"bar"]) }`),
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
|
||||
This section covers versioning of the stubs, which you can handle in a number of different ways:
|
||||
|
||||
* <<how-to-api-versioning>>
|
||||
* <<how-to-jar-versioning>>
|
||||
* <<how-to-dev-or-prod-stubs>>
|
||||
* xref:howto/how-to-do-stubs-versioning.adoc#how-to-api-versioning[API Versioning]
|
||||
* xref:howto/how-to-do-stubs-versioning.adoc#how-to-jar-versioning[JAR versioning]
|
||||
* xref:howto/how-to-do-stubs-versioning.adoc#how-to-dev-or-prod-stubs[Development or Production Stubs]
|
||||
|
||||
[[how-to-api-versioning]]
|
||||
== API Versioning
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[how-to-generate-stubs-at-runtime]]
|
||||
= How Can I Generate Stubs at Runtime
|
||||
|
||||
If you want to generate stubs at runtime for contracts, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation, or call the `withGenerateStubs(true)` method on the JUnit Rule or Extension. You can read more about this in <<project-features.adoc#features-stub-runner-generate-stubs-at-runtime, this section>> of the documentation.
|
||||
If you want to generate stubs at runtime for contracts, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation, or call the `withGenerateStubs(true)` method on the JUnit Rule or Extension. You can read more about this in xref:_project-features-stubrunner/stub-runner-generate-stubs-at-runtime.adoc[this section] of the documentation.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[[how-to-mark-contract-in-progress]]
|
||||
= How Can I Mark that a Contract Is in Progress
|
||||
|
||||
If a contract is in progress, it means that the, on the producer side, tests are not generated, but the stub is generated. You can read more about this in <<project-features.adoc#contract-dsl-in-progress, this section>> of the documentation.
|
||||
If a contract is in progress, it means that the, on the producer side, tests are not generated, but the stub is generated. You can read more about this in xref:_project-features-contract/common-top-elements.adoc#contract-dsl-in-progress[this section] of the documentation.
|
||||
|
||||
In a CI build, before going to production, you would like to ensure that no in-progress contracts are on the classpath, because they may lead to false positives. For this reason, by default, in the Spring Cloud Contract plugin, we set the value of `failOnInProgress` to `true`. If you want to allow such contracts when tests are to be generated, set the flag to `false`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
[[how-to-not-write-contracts-in-groovy]]
|
||||
= How Can I Write Contracts in a Language Other than Groovy?
|
||||
|
||||
You can write a contract in YAML. See <<project-features.adoc#contract-dsl, this section>> for more information.
|
||||
You can write a contract in YAML. See xref:_project-features-contract.adoc[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.
|
||||
|
||||
|
||||
@@ -99,7 +99,7 @@ How can you then provide a matcher for the consumer and a concrete value for the
|
||||
Spring Cloud Contract lets you provide a dynamic value. That means that it can differ for both
|
||||
sides of the communication.
|
||||
|
||||
You can read more about this in the <<project-features.adoc#contract-dsl, Contract DSL>> section.
|
||||
You can read more about this in the xref:_project-features-contract.adoc[Contract DSL] section.
|
||||
|
||||
IMPORTANT: Read the https://groovy-lang.org/json.html[Groovy docs related to JSON] to understand how to
|
||||
properly structure the request and response bodies.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[how-to-use-stubs-from-a-location]]
|
||||
= How Can I Use Stubs from a Location
|
||||
|
||||
If you want to fetch contracts or stubs from a given location without cloning a repository or fetching a JAR, use the `stubs://` protocol when providing the repository root argument for Stub Runner or the Spring Cloud Contract plugin. You can read more about this in <<project-features.adoc#features-stub-runner-stubs-protocol, this section>> of the documentation.
|
||||
If you want to fetch contracts or stubs from a given location without cloning a repository or fetching a JAR, use the `stubs://` protocol when providing the repository root argument for Stub Runner or the Spring Cloud Contract plugin. You can read more about this in xref:_project-features-stubrunner/stub-runner-stubs-protocol.adoc[this section] of the documentation.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
[[how-to-use-the-failonnostubs-feature]]
|
||||
= How Can I Make The Build Pass if There Are No Contracts or Stubs
|
||||
|
||||
If you want Stub Runner not to fail if no stubs were found, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation or call the `withFailOnNoStubs(false)` method on the JUnit Rule or Extension. You can read more about this in <<project-features.adoc#features-stub-runner-fail-on-no-stubs, this section>> of the documentation.
|
||||
If you want Stub Runner not to fail if no stubs were found, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation or call the `withFailOnNoStubs(false)` method on the JUnit Rule or Extension. You can read more about this in xref:_project-features-stubrunner/stub-runner-fail-on-no-stubs.adoc[this section] of the documentation.
|
||||
|
||||
If you want the plugins not to fail the build when no contracts were found, you can set the `failOnNoStubs` flag in Maven or call the `contractRepository { failOnNoStubs(false) }` closure in Gradle.
|
||||
|
||||
|
||||
@@ -4,18 +4,18 @@
|
||||
To learn how to set up the Maven project for Spring Cloud Contract Verifier, read the
|
||||
following sections:
|
||||
|
||||
* <<maven-add-plugin>>
|
||||
* <<maven-rest-assured>>
|
||||
* <<maven-snapshot-versions>>
|
||||
* <<maven-add-stubs>>
|
||||
* <<maven-run-plugin>>
|
||||
* <<maven-configure-plugin>>
|
||||
* <<maven-configuration-options>>
|
||||
* <<maven-single-base>>
|
||||
* <<maven-different-base>>
|
||||
* <<maven-invoking-generated-tests>>
|
||||
* <<maven-pushing-stubs-to-scm>>
|
||||
* <<maven-sts>>
|
||||
* xref:maven-project.adoc#maven-add-plugin[Adding the Maven Plugin]
|
||||
* xref:maven-project.adoc#maven-rest-assured[Maven and Rest Assured 2.0]
|
||||
* xref:maven-project.adoc#maven-snapshot-versions[Using Snapshot and Milestone Versions for Maven]
|
||||
* xref:maven-project.adoc#maven-add-stubs[Adding stubs]
|
||||
* xref:maven-project.adoc#maven-run-plugin[Run Plugin]
|
||||
* xref:maven-project.adoc#maven-configure-plugin[Configure plugin]
|
||||
* xref:maven-project.adoc#maven-configuration-options[Configuration Options]
|
||||
* xref:maven-project.adoc#maven-single-base[Single Base Class for All Tests]
|
||||
* xref:maven-project.adoc#maven-different-base[Using Different Base Classes for Contracts]
|
||||
* xref:maven-project.adoc#maven-invoking-generated-tests[Invoking Generated Tests]
|
||||
* xref:maven-project.adoc#maven-pushing-stubs-to-scm[Pushing Stubs to SCM]
|
||||
* xref:maven-project.adoc#maven-sts[Maven Plugin and STS]
|
||||
|
||||
You can also check the plugin's documentation link:../../spring-cloud-contract-maven-plugin/index.html[here].
|
||||
|
||||
@@ -520,7 +520,7 @@ goal. The following example shows how to do so:
|
||||
----
|
||||
====
|
||||
|
||||
Under <<scm-stub-downloader>>, you can find all possible
|
||||
Under xref:advanced.adoc#scm-stub-downloader[Using the SCM Stub Downloader], you can find all possible
|
||||
configuration options that you can pass through
|
||||
the `<configuration><contractsProperties>` map, a system property,
|
||||
or an environment variable. For instance, you could specify a concrete branch to checkout, instead of the default one
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
|
||||
This section dives into the details of {project-full-name}. Here you can learn about the key
|
||||
features that you may want to use and customize. If you have not already done so, you
|
||||
might want to read the "<<getting-started.adoc#getting-started>>" and
|
||||
"<<using.adoc#using>>" sections, so that you have a good grounding in the
|
||||
might want to read the "xref:getting-started.adoc[Getting Started]" and
|
||||
"xref:using.adoc[Using Spring Cloud Contract]" sections, so that you have a good grounding in the
|
||||
basics.
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ as follows:
|
||||
|
||||
If you want to learn more about any of the classes discussed in this section, you can browse the
|
||||
{github-code}[source code directly]. If you have specific questions, see the
|
||||
<<howto.adoc#howto, how-to>> section.
|
||||
xref:howto.adoc[how-to] section.
|
||||
|
||||
If you are comfortable with {project-full-name}'s core features, you can continue on and read
|
||||
about
|
||||
|
||||
@@ -9,9 +9,9 @@ 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}, 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>> :: Contract DSL, Messaging, Spring Cloud Contract Stub Runner, and Spring Cloud Contract WireMock.
|
||||
<<project-features.adoc#features-build-tools,Build Tools>> :: Maven Plugin, Gradle Plugin, and Docker.
|
||||
<<howto.adoc#howto,"`How-to`" Guides>> :: Stubs versioning, Debugging, and more.
|
||||
xref:getting-started.adoc[Getting Started] :: Introducing {project-full-name}, Developing Your First {project-full-name}-based Application
|
||||
xref:using.adoc[Using {project-full-name}] :: {project-full-name} usage examples and workflows.
|
||||
xref:project-features.adoc[{project-full-name} Features] :: Contract DSL, Messaging, Spring Cloud Contract Stub Runner, and Spring Cloud Contract WireMock.
|
||||
xref:project-features.adoc#features-build-tools[Build Tools] :: Maven Plugin, Gradle Plugin, and Docker.
|
||||
xref:howto.adoc["`How-to`" Guides] :: Stubs versioning, Debugging, and more.
|
||||
<<appendix.adoc#appendix,Appendices>> :: Properties, Metadata, Configuration, Dependencies, and more.
|
||||
|
||||
@@ -6,13 +6,13 @@ such as 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
|
||||
xref:getting-started.adoc[Getting Started] guide before diving into this
|
||||
section.
|
||||
|
||||
[[flows-provider-nexus]]
|
||||
== Provider Contract Testing with Stubs in Nexus or Artifactory
|
||||
|
||||
You can check the <<getting-started.adoc#getting-started-first-application, Developing Your First Spring Cloud Contract based application>> link to see the provider contract testing with stubs in the Nexus or Artifactory flow.
|
||||
You can check the xref:getting-started/first-application.adoc[Developing Your First Spring Cloud Contract based application] link to see the provider contract testing with stubs in the Nexus or Artifactory flow.
|
||||
|
||||
[[flows-provider-git]]
|
||||
== Provider Contract Testing with Stubs in Git
|
||||
@@ -52,11 +52,11 @@ Contract set up, together with a plugin. For an example of such a project, see
|
||||
=== The Flow
|
||||
|
||||
The flow looks exactly as the one presented in
|
||||
<<getting-started.adoc#getting-started-first-application, Developing Your First Spring Cloud Contract based application>>,
|
||||
xref:getting-started/first-application.adoc[Developing Your First Spring Cloud Contract based application],
|
||||
but the `Stub Storage` implementation is a git repository.
|
||||
|
||||
You can read more about setting up a git repository and setting consumer and producer side
|
||||
in the <<howto.adoc#how-to-use-git-as-storage,How To page>> of the documentation.
|
||||
in the xref:howto/how-to-use-git-as-storage.adoc[How To page] of the documentation.
|
||||
|
||||
[[flows-provider-git-consumer]]
|
||||
=== Consumer setup
|
||||
@@ -174,13 +174,13 @@ publish.dependsOn("publishStubsToScm")
|
||||
====
|
||||
|
||||
You can read more about setting up a git repository in the
|
||||
<<howto.adoc#how-to-use-git-as-storage,How To section>> of the documentation.
|
||||
xref:howto/how-to-use-git-as-storage.adoc[How To section] of the documentation.
|
||||
|
||||
[[flows-cdc-contracts-producer]]
|
||||
== Consumer Driven Contracts with Contracts on the Producer Side
|
||||
|
||||
See <<getting-started.adoc#getting-started-cdc, Step-by-step Guide to Consumer Driven
|
||||
Contracts (CDC) with Contracts on the Producer Side>> to see the Consumer Driven Contracts
|
||||
See xref:getting-started/cdc.adoc[Step-by-step Guide to Consumer Driven Contracts (CDC) with Contracts on the Producer Side]
|
||||
to see the Consumer Driven Contracts
|
||||
with contracts on the producer side flow.
|
||||
|
||||
[[flows-cdc-contracts-external]]
|
||||
@@ -199,7 +199,7 @@ To use consumer-driven contracts with the contracts held in an external reposito
|
||||
* For each contract producer, contains a way (for example, `pom.xml`) to install stubs
|
||||
locally through the Spring Cloud Contract Plugin (SCC Plugin).
|
||||
|
||||
For more information, see the <<howto.adoc#how-to-common-repo-with-contracts, How To section>>,
|
||||
For more information, see the xref:howto/how-to-common-repo-with-contracts.adoc[How To section],
|
||||
where we describe how to set up such a repository.
|
||||
For an example of such a project, see {samples_code}/beer_contracts[this sample].
|
||||
|
||||
@@ -454,13 +454,13 @@ The following UML diagram shows the producer process:
|
||||
[[flows-cdc-contracts-stubs-git]]
|
||||
== Consumer-driven Contracts with Contracts on the Producer Side, Pushed to Git
|
||||
|
||||
You can read the <<getting-started.adoc#getting-started-cdc, Step-by-step Guide to Consumer Driven Contracts (CDC) with contracts laying on the producer side>> to see the consumer driven contracts with contracts on the producer side flow.
|
||||
You can read the xref:getting-started/cdc.adoc[Step-by-step Guide to Consumer Driven Contracts (CDC) with contracts laying on the producer side] to see the consumer driven contracts with contracts on the producer side flow.
|
||||
|
||||
The stub storage implementation is a git repository. We describe its setup in the
|
||||
<<flows-provider-git>> section.
|
||||
xref:using.adoc#flows-provider-git[Provider Contract Testing with Stubs in Git] section.
|
||||
|
||||
You can read more about setting up a git repository for the consumer and producer sides in
|
||||
the <<howto.adoc#how-to-use-git-as-storage,How To section>> of the documentation.
|
||||
the xref:howto/how-to-use-git-as-storage.adoc[How To section] of the documentation.
|
||||
|
||||
[[flows-provider-non-spring]]
|
||||
== Provider Contract Testing with Stubs in Artifactory for a non-Spring Application
|
||||
@@ -468,7 +468,7 @@ the <<howto.adoc#how-to-use-git-as-storage,How To section>> of the documentation
|
||||
[[flows-provider-non-spring-flow]]
|
||||
=== The Flow
|
||||
|
||||
You can read <<getting-started.adoc#getting-started-first-application, Developing Your First Spring Cloud Contract-based Application>> to see the flow for provider contract testing with stubs in Nexus or Artifactory.
|
||||
You can read xref:getting-started/first-application.adoc[Developing Your First Spring Cloud Contract-based Application] to see the flow for provider contract testing with stubs in Nexus or Artifactory.
|
||||
|
||||
[[flows-provider-non-spring-consumer]]
|
||||
=== Setting up the Consumer
|
||||
@@ -858,7 +858,7 @@ The following UML diagram shows the producer flow:
|
||||
[[flows-provider-rest-docs-consumer]]
|
||||
=== Consumer Flow
|
||||
|
||||
Since the consumer flow is not affected by the tool used to generate the stubs, you can read <<getting-started.adoc#getting-started-first-application-consumer, Developing Your First Spring Cloud Contract-based Application>> to see the flow for consumer side of the provider contract testing with stubs in Nexus or Artifactory.
|
||||
Since the consumer flow is not affected by the tool used to generate the stubs, you can read xref:getting-started/first-application.adoc#getting-started-first-application-consumer[Developing Your First Spring Cloud Contract-based Application] to see the flow for consumer side of the provider contract testing with stubs in Nexus or Artifactory.
|
||||
|
||||
[[using-whats-next]]
|
||||
== What to Read Next
|
||||
|
||||
Reference in New Issue
Block a user