diff --git a/README.adoc b/README.adoc index 2a5b041edd..d82918abfd 100644 --- a/README.adoc +++ b/README.adoc @@ -455,9 +455,8 @@ all the contract are present in the producer's repository If using the *SNAPSHOT* / *Milestone* / *Release Candidate* versions please add the following section to your -Maven POM - -[source,xml,indent=0] +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven ---- @@ -513,9 +512,8 @@ Maven POM ---- -Gradle build - -[source,groovy,indent=0] +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle ---- repositories { mavenCentral() @@ -1004,26 +1002,6 @@ Spring Cloud Contract Verifier and Stub Runner are using the following libraries Below you can find some resources related to Spring Cloud Contract Verifier and Stub Runner. Note that some can be outdated since the Spring Cloud Contract Verifier project is under constant development. -===== Videos - -*Marcin Grzejszczak and Jakub Kubryński talking about Spring Cloud Contract Verifier* - -video::msRFcQM07-Y[youtube] - -https://www.youtube.com/watch?v=msRFcQM07-Y[click here to see the video] - -*Olga Maciaszek-Sharma talking about Accurest (Spring Cloud Contract Verifier predecessor)* - -video::daafmTYFoDU[youtube] - -https://www.youtube.com/watch?v=daafmTYFoDU[click here to see the video] - -*Marcin Grzejszczak and Jakub Kubryński talking about Accurest (Spring Cloud Contract Verifier predecessor)* - -video::130779882[vimeo] - -https://vimeo.com/130779882[click here to see the video] - ===== Readings - http://www.slideshare.net/MarcinGrzejszczak/stick-to-the-rules-consumer-driven-contracts-201507-confitura[Slides from Marcin Grzejszczak's talk about Accurest] diff --git a/docs-extensions/pom.xml b/docs-extensions/pom.xml new file mode 100644 index 0000000000..1d40743c79 --- /dev/null +++ b/docs-extensions/pom.xml @@ -0,0 +1,45 @@ + + + 4.0.0 + + org.springframework.cloud + spring-cloud-contract-parent + 1.0.2.BUILD-SNAPSHOT + .. + + spring-cloud-contract-docs-extensions + jar + Spring Cloud Contract Docs Extensions + Spring Cloud Docs Extensions + + 1.5.2 + + + + + maven-deploy-plugin + + true + + + + + + + org.asciidoctor + asciidoctorj + ${asciidoctorj.version} + + + junit + junit + + + org.assertj + assertj-core + test + + + diff --git a/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/CodeBlockSwitchExtension.java b/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/CodeBlockSwitchExtension.java new file mode 100644 index 0000000000..7ff31e4065 --- /dev/null +++ b/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/CodeBlockSwitchExtension.java @@ -0,0 +1,28 @@ +/* + * Copyright 2013-2016 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.cloud.asciidoctor; + +import org.asciidoctor.Asciidoctor; +import org.asciidoctor.extension.spi.ExtensionRegistry; + +public class CodeBlockSwitchExtension implements ExtensionRegistry { + + @Override + public void register(Asciidoctor asciidoctor) { + asciidoctor.javaExtensionRegistry().postprocessor(new CodeBlockSwitchPostProcessor()); + } +} \ No newline at end of file diff --git a/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/CodeBlockSwitchPostProcessor.java b/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/CodeBlockSwitchPostProcessor.java new file mode 100644 index 0000000000..75d1c1d7c9 --- /dev/null +++ b/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/CodeBlockSwitchPostProcessor.java @@ -0,0 +1,31 @@ +/* + * Copyright 2013-2016 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.cloud.asciidoctor; + +import org.asciidoctor.ast.Document; +import org.asciidoctor.extension.Postprocessor; + +class CodeBlockSwitchPostProcessor extends Postprocessor { + + private final ResourceReplacer resourceReplacer = new ResourceReplacer(); + + @Override + public String process(Document document, String output) { + return this.resourceReplacer.replaceOutput(output); + } + +} \ No newline at end of file diff --git a/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/ResourceReplacer.java b/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/ResourceReplacer.java new file mode 100644 index 0000000000..94b159d1cc --- /dev/null +++ b/docs-extensions/src/main/java/org/springframework/cloud/asciidoctor/ResourceReplacer.java @@ -0,0 +1,50 @@ +package org.springframework.cloud.asciidoctor; + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; + +/** + * @author Marcin Grzejszczak + */ +class ResourceReplacer { + + String replaceOutput(String output) { + String css = resourceToText("/codeBlockSwitch.css"); + String javascript = resourceToText("/codeBlockSwitch.js"); + String replacement = "\n" + + "\n\n" + + "\n" + + ""; + return output.replace("", replacement); + } + + private String resourceToText(String name) { + return getStringFromInputStream(getClass().getResourceAsStream(name)); + } + + private static String getStringFromInputStream(InputStream is) { + BufferedReader br = null; + StringBuilder sb = new StringBuilder(); + String line; + try { + br = new BufferedReader(new InputStreamReader(is)); + while ((line = br.readLine()) != null) { + sb.append(line); + } + } catch (IOException e) { + return ""; + } + finally { + if (br != null) { + try { + br.close(); + } catch (IOException e) { + return ""; + } + } + } + return sb.toString(); + } +} diff --git a/docs-extensions/src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry b/docs-extensions/src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry new file mode 100644 index 0000000000..15b58b59ad --- /dev/null +++ b/docs-extensions/src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry @@ -0,0 +1 @@ +org.springframework.cloud.asciidoctor.CodeBlockSwitchExtension \ No newline at end of file diff --git a/docs-extensions/src/main/resources/codeBlockSwitch.css b/docs-extensions/src/main/resources/codeBlockSwitch.css new file mode 100644 index 0000000000..6fb1947b1c --- /dev/null +++ b/docs-extensions/src/main/resources/codeBlockSwitch.css @@ -0,0 +1,23 @@ +.hidden { + display: none; +} + +.switch { + border-width: 1px 1px 0 1px; + border-style: solid; + border-color: #7a2518; + display: inline-block; +} + +.switch--item { + padding: 10px; + background-color: #ffffff; + color: #7a2518; + display: inline-block; + cursor: pointer; +} + +.switch--item.selected { + background-color: #7a2519; + color: #ffffff; +} \ No newline at end of file diff --git a/docs-extensions/src/main/resources/codeBlockSwitch.js b/docs-extensions/src/main/resources/codeBlockSwitch.js new file mode 100644 index 0000000000..13ac0fc1e5 --- /dev/null +++ b/docs-extensions/src/main/resources/codeBlockSwitch.js @@ -0,0 +1,45 @@ +function addBlockSwitches() { + $('.primary').each(function() { + primary = $(this); + createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected"); + primary.children('.title').remove(); + }); + $('.secondary').each(function(idx, node) { + secondary = $(node); + primary = findPrimary(secondary); + switchItem = createSwitchItem(secondary, primary.children('.switch')); + switchItem.content.addClass('hidden'); + findPrimary(secondary).append(switchItem.content); + secondary.remove(); + }); +} + +function createBlockSwitch(primary) { + blockSwitch = $('
'); + primary.prepend(blockSwitch); + return blockSwitch; +} + +function findPrimary(secondary) { + candidate = secondary.prev(); + while (!candidate.is('.primary')) { + candidate = candidate.prev(); + } + return candidate; +} + +function createSwitchItem(block, blockSwitch) { + blockName = block.children('.title').text(); + content = block.children('.content').first().append(block.next('.colist')); + item = $('
' + blockName + '
'); + item.on('click', '', content, function(e) { + $(this).addClass('selected'); + $(this).siblings().removeClass('selected'); + e.data.siblings('.content').addClass('hidden'); + e.data.removeClass('hidden'); + }); + blockSwitch.append(item); + return {'item': item, 'content': content}; +} + +$(addBlockSwitches); \ No newline at end of file diff --git a/docs-extensions/src/test/java/org/springframework/cloud/asciidoctor/ResourceReplacerTests.java b/docs-extensions/src/test/java/org/springframework/cloud/asciidoctor/ResourceReplacerTests.java new file mode 100644 index 0000000000..4857524769 --- /dev/null +++ b/docs-extensions/src/test/java/org/springframework/cloud/asciidoctor/ResourceReplacerTests.java @@ -0,0 +1,21 @@ +package org.springframework.cloud.asciidoctor; + +import org.junit.Test; + +import static org.assertj.core.api.BDDAssertions.then; + +/** + * @author Marcin Grzejszczak + */ +public class ResourceReplacerTests { + + @Test + public void should_process_the_resources() throws Exception { + ResourceReplacer replacer = new ResourceReplacer(); + + String output = replacer.replaceOutput(""); + + then(output).contains("http://cdnjs.cloudflare.com/ajax/libs/zepto/1.1.6/zepto.min.js"); + } + +} \ No newline at end of file diff --git a/docs/pom.xml b/docs/pom.xml index 62d7b3db3d..7189068602 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -37,6 +37,13 @@ org.asciidoctor asciidoctor-maven-plugin false + + + org.springframework.cloud + spring-cloud-contract-docs-extensions + ${project.version} + + org.apache.maven.plugins diff --git a/docs/src/main/asciidoc/verifier/contract.adoc b/docs/src/main/asciidoc/verifier/contract.adoc index 4b3f70bb21..4aece20bef 100644 --- a/docs/src/main/asciidoc/verifier/contract.adoc +++ b/docs/src/main/asciidoc/verifier/contract.adoc @@ -1,5 +1,3 @@ -:samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/master - === Contract DSL IMPORTANT: Remember that inside the contract file you have to provide the fully qualified name to @@ -113,6 +111,8 @@ include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract //include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=bodyAsXml,indent=0] //---- + + ==== Response Minimal response must contain **HTTP status code**. @@ -135,6 +135,7 @@ either via the `value` method [source,groovy,indent=0] ---- value(consumer(...), producer(...)) +value(c(...), p(...)) value(stub(...), test(...)) value(client(...), server(...)) ---- @@ -144,6 +145,7 @@ or if you're using the Groovy map notation for body you can use the `$()` method [source,groovy,indent=0] ---- $(consumer(...), producer(...)) +$(c(...), p(...)) $(stub(...), test(...)) $(client(...), server(...)) ---- @@ -364,16 +366,14 @@ First add the common jar dependency as a test dependency. That way since your contracts files are available at test resources path, automatically the common jar classes will be visible in your Groovy files. -====== Adding test dependency in Maven - -[source,xml] +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven ---- include::{samples_url}/producer/pom.xml[tags=test_dep,indent=0] ---- -====== Adding test dependency in Gradle - -[source,xml] +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle ---- include::{samples_url}/producer/build.gradle[tags=test_dep,indent=0] ---- @@ -382,18 +382,14 @@ include::{samples_url}/producer/build.gradle[tags=test_dep,indent=0] Now you have to add the dependency for the plugin to reuse at runtime. -====== Adding test plugin dependency in Maven - -[source,xml] +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven ---- include::{samples_url}/producer/pom.xml[tags=test_dep_in_plugin,indent=0] ---- -====== Adding test plugin dependency in Gradle - -Inside your `buildscript { dependencies {} }` section pass the following: - -[source,groovy] +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle ---- include::{samples_url}/producer/build.gradle[tags=test_dep_in_plugin,indent=0] ---- diff --git a/docs/src/main/asciidoc/verifier/introduction.adoc b/docs/src/main/asciidoc/verifier/introduction.adoc index fa313de603..5f9939af55 100644 --- a/docs/src/main/asciidoc/verifier/introduction.adoc +++ b/docs/src/main/asciidoc/verifier/introduction.adoc @@ -135,16 +135,14 @@ all the contract are present in the producer's repository If using the *SNAPSHOT* / *Milestone* / *Release Candidate* versions please add the following section to your -Maven POM - -[source,xml,indent=0] +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven ---- include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=repos,indent=0] ---- -Gradle build - -[source,groovy,indent=0] +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle ---- include::{introduction_url}/samples/standalone/dsl/http-server/build.gradle[tags=deps_repos,indent=0] ---- @@ -468,26 +466,6 @@ Spring Cloud Contract Verifier and Stub Runner are using the following libraries Below you can find some resources related to Spring Cloud Contract Verifier and Stub Runner. Note that some can be outdated since the Spring Cloud Contract Verifier project is under constant development. -===== Videos - -*Marcin Grzejszczak and Jakub Kubryński talking about Spring Cloud Contract Verifier* - -video::msRFcQM07-Y[youtube] - -https://www.youtube.com/watch?v=msRFcQM07-Y[click here to see the video] - -*Olga Maciaszek-Sharma talking about Accurest (Spring Cloud Contract Verifier predecessor)* - -video::daafmTYFoDU[youtube] - -https://www.youtube.com/watch?v=daafmTYFoDU[click here to see the video] - -*Marcin Grzejszczak and Jakub Kubryński talking about Accurest (Spring Cloud Contract Verifier predecessor)* - -video::130779882[vimeo] - -https://vimeo.com/130779882[click here to see the video] - ===== Readings - http://www.slideshare.net/MarcinGrzejszczak/stick-to-the-rules-consumer-driven-contracts-201507-confitura[Slides from Marcin Grzejszczak's talk about Accurest] diff --git a/docs/src/main/asciidoc/verifier/messaging.adoc b/docs/src/main/asciidoc/verifier/messaging.adoc index 19ed1da0ae..74f2dcdbcc 100644 --- a/docs/src/main/asciidoc/verifier/messaging.adoc +++ b/docs/src/main/asciidoc/verifier/messaging.adoc @@ -132,15 +132,14 @@ and proper stubbed routes are created. For more information please consult the Stub Runner Messaging sections. -===== Gradle Setup +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- +include::{standalone_messaging_samples_path}/stream-sink/pom.xml[tags=jars,indent=0] +---- -Example of Spring Cloud Contract Verifier Gradle setup: - -[source,groovy,indent=0] +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle ---- include::{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0] ---- - -===== Maven Setup - -Example of Maven can be found in the https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples/standalone/messaging/stream-sink/pom.xml[Stream Sink sample] diff --git a/docs/src/main/asciidoc/verifier/spring-cloud-contract-verifier.adoc b/docs/src/main/asciidoc/verifier/spring-cloud-contract-verifier.adoc index b4f9b24bba..1d46d7a178 100644 --- a/docs/src/main/asciidoc/verifier/spring-cloud-contract-verifier.adoc +++ b/docs/src/main/asciidoc/verifier/spring-cloud-contract-verifier.adoc @@ -6,7 +6,9 @@ :verifier_core_path: {verifier_root_path} :stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner :standalone_samples_path: {samples_path}/standalone/dsl +:standalone_messaging_samples_path: {samples_path}/standalone/messaging :tests_path: ../../../../../tests +:samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/master include::introduction.adoc[] diff --git a/docs/src/main/asciidoc/verifier/stubrunner.adoc b/docs/src/main/asciidoc/verifier/stubrunner.adoc index 661776e027..80cae8436e 100644 --- a/docs/src/main/asciidoc/verifier/stubrunner.adoc +++ b/docs/src/main/asciidoc/verifier/stubrunner.adoc @@ -12,36 +12,43 @@ automatically for you. Add the additional snapshot repository to your build.gradle to use snapshot versions which are automatically uploaded after every successful build: -[source,groovy,indent=0] ----- -include::{standalone_samples_path}/http-server/build.gradle[tags=repos,indent=0] -} ----- - -for Maven - -[source,xml,indent=0] +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven ---- include::{standalone_samples_path}/http-server/pom.xml[tags=repos,indent=0] ---- +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +include::{standalone_samples_path}/http-server/build.gradle[tags=repos,indent=0] +---- + ==== Publishing stubs as JARs The easiest approach would be to centralize the way stubs are kept. For example you can keep them as JARs in a Maven repository. -===== Gradle +TIP: For both Maven and Gradle the setup comes out of the box. But you can customize it if you want to. -Example of Spring Cloud Contract Verifier Gradle setup: +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + +include::{samples_url}/producer_with_restdocs/pom.xml[tags=skip_jar,indent=0] -[source,groovy,indent=0] + +include::{samples_url}/producer_with_restdocs/pom.xml[tags=assembly,indent=0] + + +include::{samples_url}/producer_with_restdocs/src/assembly/stub.xml[indent=0] +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle ---- include::{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0] ---- -===== Maven - -Example of Maven can be found in the https://github.com/spring-cloud/spring-cloud-contract/[Spring Cloud Contract Verifier README] - ==== Modules include::{stubrunner_core_path}/README.adoc[] diff --git a/pom.xml b/pom.xml index 0546ec670b..5520d4adaf 100644 --- a/pom.xml +++ b/pom.xml @@ -37,6 +37,7 @@ spring-cloud-contract-dependencies + docs-extensions docs spring-cloud-contract-wiremock spring-cloud-contract-verifier diff --git a/samples/standalone/messaging/stream-sink/pom.xml b/samples/standalone/messaging/stream-sink/pom.xml index a76f8c7f10..0cd6cc9088 100644 --- a/samples/standalone/messaging/stream-sink/pom.xml +++ b/samples/standalone/messaging/stream-sink/pom.xml @@ -24,6 +24,7 @@ 1.0.2.BUILD-SNAPSHOT + org.springframework.cloud @@ -54,6 +55,8 @@ + + diff --git a/scripts/generateDocs.sh b/scripts/generateDocs.sh index c730dd17c3..77ee034333 100755 --- a/scripts/generateDocs.sh +++ b/scripts/generateDocs.sh @@ -7,7 +7,7 @@ set -e echo "Generating docs for Spring Cloud Contract" echo "Building main docs" -./mvnw clean install -P docs -DskipTests=true --pl docs +./mvnw clean install -P docs -DskipTests=true --pl docs-extensions,docs echo "Building maven plugin docs" ./mvnw site -DskipTests=true --pl spring-cloud-contract-tools/spring-cloud-contract-maven-plugin