diff --git a/docs/src/main/asciidoc/_project-features-contract.adoc b/docs/src/main/asciidoc/_project-features-contract.adoc index f9d721b10c..d8137c05a0 100644 --- a/docs/src/main/asciidoc/_project-features-contract.adoc +++ b/docs/src/main/asciidoc/_project-features-contract.adoc @@ -6,7 +6,9 @@ Spring Cloud Contract supports out of the box following types of DSL. * written in `Groovy` * written in `YAML` -* written in `Java` + +TIP: If you're not familiar with Groovy, don't worry - you can use Java syntax in the +Groovy DSL files as well. If you decide to write the contract in Groovy, do not be alarmed if you have not used Groovy before. Knowledge of the language is not really needed, as the Contract DSL uses only a @@ -43,9 +45,6 @@ TIP: You can compile contracts to stubs mapping using standalone maven command: [[contract-limitations]] === Limitations -WARNING: Spring Cloud Contract Verifier does not properly support XML. Please use JSON or -help us implement this feature. - WARNING: The support for verifying the size of JSON arrays is experimental. If you want to turn it on, please set the value of the following system property to `true`: `spring.cloud.contract.verifier.assert.size`. By default, this feature is set to `false`. @@ -64,7 +63,6 @@ The following sections describe the most common top-level elements: * <> * <> * <> -* <> [[contract-dsl-description]] ==== Description @@ -205,8 +203,18 @@ include::{verifier_core_path}/src/test/resources/yml/contract_pdf.yml[indent=0] IMPORTANT: You should use this approach whenever you want to work with binary payloads both for HTTP and messaging. +[[features-http]] +== Contracts for HTTP + +Spring Cloud Contract allows you to verify applications that use REST or HTTP as a +means of communication. Spring Cloud Contract verifies that for a request that matches the +criteria from the `request` part of the contract, the server provides a response that is in +keeping with the `response` part of the contract. Subsequently, the contracts are used to +generate wiremock stubs that for any request matching the provided criteria, will provide a +suitable response. + [[contract-dsl-http-top-level-elements]] -==== HTTP Top-Level Elements +=== HTTP Top-Level Elements The following methods can be called in the top-level closure of a contract definition. `request` and `response` are mandatory. `priority` is optional. @@ -1150,8 +1158,8 @@ response: ==== [[contract-dsl-xml]] -=== XML Support for REST -For REST contracts, we also support XML request and response body. +=== XML Support for HTTP +For HTTP contracts, we also support XML request and response body. The XML body has to be passed within the `body` element as a `String` or `GString`. Also body matchers can be provided for both request and response. In place of the `jsonPath(...)` method, the `org.springframework.cloud.contract.spec.internal.BodyMatchers.xPath` diff --git a/docs/src/main/asciidoc/documentation-overview.adoc b/docs/src/main/asciidoc/documentation-overview.adoc index 8e9d44faeb..2db0e9eb79 100644 --- a/docs/src/main/asciidoc/documentation-overview.adoc +++ b/docs/src/main/asciidoc/documentation-overview.adoc @@ -32,13 +32,13 @@ starting out with {project-full-name}, try one of the https://spring.io/guides[g * Ask a question. We monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/{project-name}[`{project-name}`]. * Report bugs with {project-full-name} at https://github.com/spring-cloud/{project-name}/issues. +* Chat with us at http://https://gitter.im/spring-cloud/{project-name}[{project-full-name} Gitter] NOTE: All of {project-full-name} is open source, including the documentation. If you find problems with the docs or if you want to improve them, please {github-code}[get involved]. - [[contract-documentation-first-steps]] == First Steps If you are getting started with {project-full-name} or 'Spring' in general, start with @@ -50,8 +50,8 @@ If you are getting started with {project-full-name} or 'Spring' in general, star <> * *Tutorial:* <> | -<> | -<> | +<> | +<> | <> @@ -73,7 +73,15 @@ you covered>>: ** <> ** <> +TIP: We talk about *Provider Contracts* when it's 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 can't +directly collaborate with their consumers; for example, when there are too many consumers, +the consumers are external (don't work within the same company). +TIP: We use the term *Consumer-Driven Contracts* to refer to workflows where the consumers of an API +play a vital role in the process of creating the contracts; it's the recommended approach, easy +to implement when both producer and consumer teams work for the same organisations and the number +of consumers is not extremely large. == Learning about {project-full-name} Features Need more details about {project-full-name}'s core features? @@ -81,18 +89,20 @@ Need more details about {project-full-name}'s core features? * *Core Features:* <> | -<> +<> | +<> * *Integrations:* <> | -<> | <> | <> +<> * *Modules:* <> | <> -* *Build tools:* -link:maven-project.html[Maven] | -link:gradle-project.html[Gradle] | +// TODO: links don't work in "build Tools" section +* *Build Tools:* +link:maven-project.html[Contract Verifier - Maven] | +link:gradle-project.html[Contract Verifier - Gradle] | link:docker-project.html[Docker] diff --git a/docs/src/main/asciidoc/getting-started.adoc b/docs/src/main/asciidoc/getting-started.adoc index 2e6a4a3945..b10b6972c1 100644 --- a/docs/src/main/asciidoc/getting-started.adoc +++ b/docs/src/main/asciidoc/getting-started.adoc @@ -13,7 +13,7 @@ principles as we go. [[getting-started-introducing-spring-cloud-contract]] == Introducing Spring Cloud Contract -Spring Cloud Contract moves TDD to the level of software architecture. It allows to perform consumer, consumer-driven and producer-driven contract testing. +Spring Cloud Contract moves TDD to the level of software architecture. It allows to perform consumer-driven and producer-driven contract testing. [[getting-started-introducing-spring-cloud-contract-history]] === History @@ -914,7 +914,7 @@ the server side. Currently, the consumer side work is done. [[getting-started-cdc-producer]] === Producer side (Fraud Detection server) -As a developer of the Fraud Detection server (a server to the Loan Issuance service) we would like to: +As a developer of the Fraud Detection server (a server to the Loan Issuance service) I would like to: - take over the pull request - write the missing implementation @@ -1073,7 +1073,7 @@ application and the stub artifacts. [[getting-started-cdc-consumer-final]] === Consumer Side (Loan Issuance) Final Step -As a developer of the Loan Issuance service (a consumer of the Fraud Detection server) we will want to: +As a developer of the Loan Issuance service (a consumer of the Fraud Detection server) I will want to: - merge our feature branch to `master` - switch to online mode of working @@ -1120,7 +1120,7 @@ include::{introduction_url}/samples/standalone/dsl/http-client/src/test/resource That's it! [[getting-started-whats-next]] -== What to Read Next +== Next Steps Hopefully, this section provided some of the {project-full-name} basics and got you on your way to writing your own applications. If you are a task-oriented type of developer, you might want to jump over to https://spring.io and check out some of the