diff --git a/docs/src/main/asciidoc/getting-started.adoc b/docs/src/main/asciidoc/getting-started.adoc index 845c181903..3176d9aa4d 100644 --- a/docs/src/main/asciidoc/getting-started.adoc +++ b/docs/src/main/asciidoc/getting-started.adoc @@ -18,7 +18,7 @@ Spring Cloud Contract moves TDD to the level of software architecture. It allows Before becoming Spring Cloud Contract, this project was called https://github.com/Codearte/accurest[Accurest]. It was created by https://twitter.com/mgrzejszczak[Marcin Grzejszczak] and https://twitter.com/jkubrynski[Jakub Kubrynski] -from (https://github.com/Codearte[Codearte]. +from (https://github.com/Codearte[Codearte]). The `0.1.0` release took place on 26 Jan 2015 and it became stable with `1.0.0` release on 29 Feb 2016. @@ -141,12 +141,12 @@ You can find a somewhat longer tour "API Producer"->"API Producer": define contracts "API Producer"->"Build": run build "Build"->"SCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar) -"Build"->"Nexus / Artifactory": upload contracts \nand stubs and the project arifact +"Build"->"Stub Storage": upload contracts \nand stubs and the project arifact "Build"->"API Producer": Build successful "API Consumer"->"API Consumer": add SCC Stub Runner \ndependency "API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test -"SCC Stub Runner"->"Nexus / Artifactory": test asks for [API Producer] stubs -"Nexus / Artifactory"->"SCC Stub Runner": fetch the [API Producer] stubs +"SCC Stub Runner"->"Stub Storage": test asks for [API Producer] stubs +"Stub Storage"->"SCC Stub Runner": fetch the [API Producer] stubs "SCC Stub Runner"->"SCC Stub Runner": run in memory\n HTTP server stubs "API Consumer"->"SCC Stub Runner": send a request \nto the HTTP server stub "SCC Stub Runner"->"API Consumer": communication is correct @@ -264,6 +264,8 @@ This brief tour walks through using Spring Cloud Contract: You can find an even more brief tour <>. +For the sake of this example the `Stub Storage` will be Nexus / Artifactory. + image::getting-started-three-second.png[Getting started first application] [[getting-started-first-application-producer]] @@ -604,11 +606,19 @@ Assume that `Loan Issuance` is a client to the `Fraud Detection` server. In the sprint, we must develop a new feature: if a client wants to borrow too much money, then we mark the client as a fraud. -Technical remark - Fraud Detection has an `artifact-id` of `http-server`, while Loan -Issuance has an artifact-id of `http-client`, and both have a `group-id` of `com.example`. +Technical remarks -Social remark - both client and server development teams need to communicate directly and -discuss changes while going through the process. CDC is all about communication. +* Fraud Detection has an `artifact-id` of `http-server`, +* Loan +Issuance has an artifact-id of `http-client` +* both have a `group-id` of `com.example` +* For the sake of this example the `Stub Storage` will be Nexus / Artifactory + +Social remarks + +* both client and server development teams need to communicate directly and +discuss changes while going through the process +* CDC is all about communication. The https://github.com/spring-cloud/spring-cloud-contract/tree/{branch}/samples/standalone/dsl/http-server[server side code is available here] and https://github.com/spring-cloud/spring-cloud-contract/tree/{branch}/samples/standalone/dsl/http-client[the @@ -920,7 +930,7 @@ Let's look at the Fraud Detection flow: "Fraud\nDetection\nBuild"->"Fraud\nDetection": all the tests passed! "Fraud\nDetection"->"Fraud\nDetection": commit and push changes "Fraud\nDetection"->"CI": commit pushed!\nTriggers the build -"CI"->"Nexus / Artifactory": build successful,\nupload artifacts +"CI"->"Stub Storage": build successful,\nupload artifacts ---- *Take over the pull request.* @@ -1059,10 +1069,10 @@ As a developer of the Loan Issuance service (a consumer of the Fraud Detection s [plantuml, getting-started-cdc-client, png] ---- "Loan\nIssuance"->"Loan\nIssuance": merge the\nfeature branch\nto master branch -"Loan\nIssuance"->"Loan\nIssuance": setup SCC Stub Runner\nto fetch stubs\nfrom Nexus / Artifactory -"Loan\nIssuance"->"LI\nSCC\nStub Runner": start stubs\nof FD from\nNexus / Artifactory -"LI\nSCC\nStub Runner"->"Nexus / Artifactory": find stubs of [FD] -"Nexus / Artifactory"->"LI\nSCC\nStub Runner": stubs of [FD] found +"Loan\nIssuance"->"Loan\nIssuance": setup SCC Stub Runner\nto fetch stubs\nfrom Stub Storage +"Loan\nIssuance"->"LI\nSCC\nStub Runner": start stubs\nof FD from\nStub Storage +"LI\nSCC\nStub Runner"->"Stub Storage": find stubs of [FD] +"Stub Storage"->"LI\nSCC\nStub Runner": stubs of [FD] found "LI\nSCC\nStub Runner"->"FD stub": run stubs of [FD] "FD stub"->"LI\nSCC\nStub Runner": [FD] stub is running "LI\nSCC\nStub Runner"->"Loan\nIssuance": stubs running and ready for the test diff --git a/docs/src/main/asciidoc/index.htmladoc b/docs/src/main/asciidoc/index.htmladoc index 795c5a05af..8e7c3bcbd1 100644 --- a/docs/src/main/asciidoc/index.htmladoc +++ b/docs/src/main/asciidoc/index.htmladoc @@ -8,9 +8,9 @@ The reference documentation consists of the following sections: [horizontal] <> :: Legal information. <> :: About the Documentation, Getting Help, First Steps, and more. -<> :: Introducing Spring Cloud Contract, System Requirements, Developing Your First Spring Cloud Contract based Application -<> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, and more. -<> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more. +<> :: Introducing {project-full-name}, System Requirements, Developing Your First {project-full-name} based Application +<> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, and more. +<> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more. <> :: Monitoring, Metrics, Auditing, and more. <> :: Maven Plugin, Gradle Plugin. <> :: Application Development, Configuration, Embedded Servers, Data Access, and many more. diff --git a/docs/src/main/asciidoc/index.htmlpdfadoc b/docs/src/main/asciidoc/index.htmlpdfadoc index 7f92b081e8..5e8932ca92 100644 --- a/docs/src/main/asciidoc/index.htmlpdfadoc +++ b/docs/src/main/asciidoc/index.htmlpdfadoc @@ -7,8 +7,8 @@ include::_attributes.adoc[] include::legal.adoc[leveloffset=+1] include::documentation-overview.adoc[leveloffset=+1] include::getting-started.adoc[leveloffset=+1] -include::using-spring-cloud-contract.adoc[leveloffset=+1] -include::spring-cloud-contract-features.adoc[leveloffset=+1] +include::using.adoc[leveloffset=+1] +include::project-features.adoc[leveloffset=+1] include::build-tool-plugins.adoc[leveloffset=+1] include::howto.adoc[leveloffset=+1] include::appendix.adoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/src/main/asciidoc/index.htmlsingleadoc b/docs/src/main/asciidoc/index.htmlsingleadoc index 7f92b081e8..5e8932ca92 100644 --- a/docs/src/main/asciidoc/index.htmlsingleadoc +++ b/docs/src/main/asciidoc/index.htmlsingleadoc @@ -7,8 +7,8 @@ include::_attributes.adoc[] include::legal.adoc[leveloffset=+1] include::documentation-overview.adoc[leveloffset=+1] include::getting-started.adoc[leveloffset=+1] -include::using-spring-cloud-contract.adoc[leveloffset=+1] -include::spring-cloud-contract-features.adoc[leveloffset=+1] +include::using.adoc[leveloffset=+1] +include::project-features.adoc[leveloffset=+1] include::build-tool-plugins.adoc[leveloffset=+1] include::howto.adoc[leveloffset=+1] include::appendix.adoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/src/main/asciidoc/using.adoc b/docs/src/main/asciidoc/using.adoc index 81ba85c51e..8aac5d4a88 100644 --- a/docs/src/main/asciidoc/using.adoc +++ b/docs/src/main/asciidoc/using.adoc @@ -20,6 +20,149 @@ You can also check the https://cloud-samples.spring.io/spring-cloud-contract-sam [[flows-provider-git]] == Provider contract testing with stubs in Git +In this flow, we will perform the provider contract testing (producer has no knowledge of how consumers use their API). The stubs will be uploaded to a separate repository (they will not be uploaded to Artifactory / Nexus). + +Prerequisites: + +* Git repository that +** will contain all the stubs for each producer +** for an example of such a project you can check the samples +{samples_code}/contract_git[check the samples ] or {samples_code}/contract_git[check the samples here] +** as a result of pushing stubs there, the repository will have the following structure ++ +``` +$ tree . +└── META-INF +   └── folder.with.group.id.as.its.name +   └── folder-with-artifact-id +   └── folder-with-version +   ├── contractA.groovy +   ├── contractB.yml +   └── contractC.groovy + +``` +* Consumer code that has Spring Cloud Contract Stub Runner setup +** for an example of such a project you can {samples_code}/consumer[check the samples] and search for a `BeerControllerGitTest` test +* Producer code that has Spring Cloud Contract setup together with a plugin +** for an example of such a project you can {samples_code}/producer_with_empty_git[check the samples] + +[[flows-provider-git-flow]] +=== The flow + +The flow looks exactly as the one presented in he <> section, but the `Stub Storage` implementation will be a git repository. + +You can read more about setting up git repository as a git storage and setting consumer and producer side in the <> of the documentation. + +[[flows-provider-git-consumer]] +=== Consumer setup + +In order to fetch the stubs from a git repository instead of Nexus / Artifactory, you need to use the `git` protocol in the URL of the `repositoryRoot` property in Stub Runner. Below you have an example of how to set it up. + +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.Annotation +---- +@AutoConfigureStubRunner( +stubsMode = StubRunnerProperties.StubsMode.REMOTE, + repositoryRoot = "git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git", + ids = "com.example:artifact-id:0.0.1") +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 4 Rule +---- +@Rule + public StubRunnerRule rule = new StubRunnerRule() + .downloadStub("com.example","artifact-id", "0.0.1") + .repoRoot("git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE); +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 5 Extension +---- +@Rule + public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() + .downloadStub("com.example","artifact-id", "0.0.1") + .repoRoot("git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE); +---- + +[[flows-provider-git-producer]] +=== Producer setup + +In order to push the stubs to a git repository instead of Nexus / Artifactory, you need to use the `git` protocol in the URL of the plugin setup. Also you need to explicitly tell the plugin to push the stubs at the end of the build process. + +==== +[source,xml,indent=0,role="primary"] +.maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + + + + git://git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git + + + + ${project.groupId} + ${project.artifactId} + ${project.version} + + + + REMOTE + + + + package + + + pushStubsToScm + + + + +---- + +[source,groovy,indent=0,role="secondary"] +.gradle +---- +contracts { + // We want to pick contracts from a Git repository + contractDependency { + stringNotation = "${project.group}:${project.name}:${project.version}" + } + /* + We reuse the contract dependency section to set up the path + to the folder that contains the contract definitions. In our case the + path will be /groupId/artifactId/version/contracts + */ + contractRepository { + repositoryUrl = "git://git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git" + } + // The mode can't be classpath + contractsMode = "REMOTE" + // Base class mappings etc. +} + +/* +In this scenario we want to publish stubs to SCM whenever +the `publish` task is executed +*/ +publish.dependsOn("publishStubsToScm") +---- +==== + +You can read more about setting up git repository as a git storage in the <> of the documentation. + [[flows-cdc-contracts-producer]] == Consumer Driven Contracts with contracts on the producer side @@ -35,7 +178,7 @@ You can check the https://cloud-samples.spring.io/spring-cloud-contract-samples/ Prerequisites: * Git repository that -** will contain all the contract defintiions for each producer +** will contain all the contract definitions for each producer ** can package the contract definitions in a JAR ** for each contract producer contains a way (e.g. `pom.xml`) to install stubs locally via the Spring Cloud Contract Plugin (SCC Plugin) ** for more information please visit the <> where we describe how to set up such a repository @@ -44,6 +187,7 @@ Prerequisites: ** for an example of such a project you can {samples_code}/consumer[check the samples] * Producer code that has Spring Cloud Contract setup together with a plugin ** for an example of such a project you can {samples_code}/producer_with_external_contracts[check the samples] +* The `Stub Storage` will be Nexus / Artifactory At a high level the flow looks as follows: @@ -235,27 +379,43 @@ contracts { "Producer\nBuild"->"Producer": the tests passed "Producer"->"Repo\nwith\ncontracts": merge the pull request "Repo\nwith\ncontracts"->"CI": build and upload the\ncontract definitions artifact -"CI"->"Nexus / Artifactory": upload the\ncontract definitions +"CI"->"Stub Storage": upload the\ncontract definitions "Producer"->"Producer": setup the SCC Plugin\nto work remotely "Producer"->"Producer": merge the code\nwith the implementation "Producer"->"CI": build and upload\nthe artifacts "CI"->"Producer\nBuild\non CI": generate tests,\nstubs\nand stub jar "Producer\nBuild\non CI"->"SCC\nPlugin": generate tests,\nstubs\nand stub jar -"SCC\nPlugin"->"Nexus / Artifactory": fetch the contract definitions -"Nexus / Artifactory"->"SCC\nPlugin": contract definitions found +"SCC\nPlugin"->"Stub Storage": fetch the contract definitions +"Stub Storage"->"SCC\nPlugin": contract definitions found "SCC\nPlugin"->"SCC\nPlugin": generate tests "Producer\nBuild\non CI"->"CI": the build passed -"Producer\nBuild\non CI"->"Nexus / Artifactory": upload the application JAR\nand the stubs jar +"Producer\nBuild\non CI"->"Stub Storage": upload the application JAR\nand the stubs jar ---- [[flows-cdc-contracts-stubs-git]] -== Consumer Driven Contracts with contracts and stubs in git +== Consumer Driven Contracts with contracts on the producer side, pushed to git + +You can check the <> link to see the Consumer Driven Contracts with contracts on the producer side flow. + +The Stub Storage implementation would be the git repository. We describe its setup in the <> section. + +You can read more about setting up git repository as a git storage and setting consumer and producer side in the <> of the documentation. [[flows-provider-non-spring]] -== Provider contract testing with stubs in artifactory for a non Spring application +== Provider contract testing with stubs in Artifactory for a non Spring application + +[[flows-provider-non-spring-flow]] +=== The flow + +You can check the <> link to see the provider contract testing with stubs in Nexus / Artifactory flow. + +[[flows-provider-non-spring-consumer]] +=== Consumer setup + +For the consumer side, it's enough to use a JUnit rule. [[flows-provider-non-jvm]] -== Provider contract testing with stubs in artifactory in non JVM world +== Provider contract testing with stubs in Artifactory in non JVM world [[flows-provider-rest-docs]] == Provider contract testing with REST Docs and stubs in Artifactory