Add support for generating snippets in Markdown

This commit introduces support for generating snippets formatted
using Markdown. Asciidoctor remains the default.

A new SnippetFormat abstraction has been introduced with Asciidoctor
and Markdown implementations provided out of the box.
Markdown-formatted templates are also provided for all of the default
snippets.

Please refer to the updated reference documentation for further
details.

Closes gh-150
Closes gh-19

Author: wilkinsona

config/checkstyle/checkstyle.xml

@@ -73,7 +73,7 @@
 		<module name="AvoidStarImport" />
 		<module name="AvoidStaticImport">
 			<property name="excludes"
-				value="com.jayway.restassured.RestAssured.*, org.junit.Assert.*, org.junit.Assume.*, org.hamcrest.CoreMatchers.*, org.hamcrest.Matchers.*, org.mockito.Mockito.*, org.mockito.BDDMockito.*, org.mockito.Matchers.*, org.springframework.restdocs.curl.CurlDocumentation.*, org.springframework.restdocs.headers.HeaderDocumentation.*, org.springframework.restdocs.hypermedia.HypermediaDocumentation.*, org.springframework.restdocs.mockmvc.IterableEnumeration.*, org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*, org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*, org.springframework.restdocs.payload.PayloadDocumentation.*, org.springframework.restdocs.operation.preprocess.Preprocessors.*, org.springframework.restdocs.request.RequestDocumentation.*, org.springframework.restdocs.restassured.RestAssuredRestDocumentation.*, org.springframework.restdocs.restassured.operation.preprocess.RestAssuredPreprocessors.*, org.springframework.restdocs.snippet.Attributes.*, org.springframework.restdocs.test.SnippetMatchers.*, org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*, org.springframework.test.web.servlet.result.MockMvcResultMatchers.*" />
+				value="com.jayway.restassured.RestAssured.*, org.junit.Assert.*, org.junit.Assume.*, org.hamcrest.CoreMatchers.*, org.hamcrest.Matchers.*, org.mockito.Mockito.*, org.mockito.BDDMockito.*, org.mockito.Matchers.*, org.springframework.restdocs.curl.CurlDocumentation.*, org.springframework.restdocs.headers.HeaderDocumentation.*, org.springframework.restdocs.hypermedia.HypermediaDocumentation.*, org.springframework.restdocs.mockmvc.IterableEnumeration.*, org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*, org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*, org.springframework.restdocs.payload.PayloadDocumentation.*, org.springframework.restdocs.operation.preprocess.Preprocessors.*, org.springframework.restdocs.request.RequestDocumentation.*, org.springframework.restdocs.restassured.RestAssuredRestDocumentation.*, org.springframework.restdocs.restassured.operation.preprocess.RestAssuredPreprocessors.*, org.springframework.restdocs.snippet.Attributes.*, org.springframework.restdocs.snippet.SnippetFormats.*, org.springframework.restdocs.test.SnippetMatchers.*, org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*, org.springframework.test.web.servlet.result.MockMvcResultMatchers.*" />
 		</module>
 		<module name="IllegalImport" />
 		<module name="RedundantImport" />

docs/src/docs/asciidoc/configuration.adoc

@@ -42,8 +42,7 @@ TIP: To configure a request's context path, use the `contextPath` method on
 [[configuration-snippet-encoding]]
 === Snippet encoding
 
-The default encoding used by Asciidoctor is `UTF-8`. Spring REST Docs adopts the same
-default for the snippets that it generates. You can change the default snippet encoding
+The default snippet encoding is `UTF-8`. You can change the default snippet encoding
 using the `RestDocumentationConfigurer` API. For example, to use `ISO-8859-1`:
 
 [source,java,indent=0,role="primary"]
@@ -60,6 +59,26 @@ include::{examples-dir}/com/example/restassured/CustomEncoding.java[tags=custom-
 
 
 
+[[configuration-snippet-format]]
+=== Snippet format
+
+The default snippet format is Asciidoctor. Markdown is also supported out of the box. You
+can change the default format using the `RestDocumentationConfigurer` API:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/CustomFormat.java[tags=custom-format]
+----
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/CustomFormat.java[tags=custom-format]
+----
+
+
+
 [[configuration-default-snippets]]
 === Default snippets
 

docs/src/docs/asciidoc/index.adoc

@@ -26,4 +26,5 @@ include::documenting-your-api.adoc[]
 include::customizing-requests-and-responses.adoc[]
 include::configuration.adoc[]
 include::working-with-asciidoctor.adoc[]
+include::working-with-markdown.adoc[]
 include::contributing.adoc[]

docs/src/docs/asciidoc/introduction.adoc

@@ -6,8 +6,9 @@ services that is accurate and readable.
 
 Writing high-quality documentation is difficult. One way to ease that difficulty is to use
 tools that are well-suited to the job. To this end, Spring REST Docs uses
-http://asciidoctor.org[Asciidoctor]. Asciidoctor processes plain text and produces
-HTML, styled and layed out to suit your needs.
+http://asciidoctor.org[Asciidoctor] by default. Asciidoctor processes plain text and
+produces HTML, styled and layed out to suit your needs. If you prefer, Spring REST Docs
+can also be configured to use Markdown.
 
 Spring REST Docs makes use of snippets produced by tests written with
 {spring-framework-docs}/#spring-mvc-test-framework[Spring MVC Test] or

docs/src/docs/asciidoc/working-with-markdown.adoc

@@ -0,0 +1,28 @@
+[[working-with-markdown]]
+== Working with Markdown
+
+This section describes any aspects of working with Markdown that are particularly
+relevant to Spring REST Docs.
+
+
+
+[[working-with-markdown-limitations]]
+=== Limitations
+
+Markdown was originally designed for people writing for the web and, as such, isn't
+as well-suited to writing documentation as Asciidoctor. Typically, these limitations
+are overcome by using another tool that builds on top of Markdown.
+
+Markdown has no official support for tables. Spring REST Docs' default Markdown snippet
+templates use https://michelf.ca/projects/php-markdown/extra/#table[Markdown Extra's table
+format].
+
+
+
+[[working-with-markdown-including-snippets]]
+=== Including snippets
+
+Markdown has no built-in support for including one Markdown file in another. To include
+the generated snippets of Markdown in your documentation, you should use an additional
+tool that supports this functionality. One example that's particularly well-suited to
+documenting APIs is https://github.com/tripit/slate[Slate].

docs/src/test/java/com/example/mockmvc/CustomFormat.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2014-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 com.example.mockmvc;
+
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+
+import org.junit.Before;
+import org.junit.Rule;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.snippet.SnippetFormats;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+import org.springframework.web.context.WebApplicationContext;
+
+public class CustomFormat {
+
+	@Rule
+	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+
+	@Autowired
+	private WebApplicationContext context;
+
+	private MockMvc mockMvc;
+
+	@Before
+	public void setUp() {
+		// tag::custom-format[]
+		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
+				.apply(documentationConfiguration(this.restDocumentation)
+						.snippets().withFormat(SnippetFormats.markdown()))
+				.build();
+		// end::custom-format[]
+	}
+
+}

docs/src/test/java/com/example/restassured/CustomFormat.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2014-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 com.example.restassured;
+
+import org.junit.Before;
+import org.junit.Rule;
+import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.snippet.SnippetFormats;
+
+import com.jayway.restassured.builder.RequestSpecBuilder;
+import com.jayway.restassured.specification.RequestSpecification;
+
+import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.documentationConfiguration;
+
+public class CustomFormat {
+
+	@Rule
+	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+
+	private RequestSpecification spec;
+
+	@Before
+	public void setUp() {
+		// tag::custom-format[]
+		this.spec = new RequestSpecBuilder()
+				.addFilter(documentationConfiguration(this.restDocumentation)
+						.snippets().withFormat(SnippetFormats.markdown()))
+				.build();
+		// end::custom-format[]
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/config/RestDocumentationConfigurer.java

@@ -93,13 +93,20 @@ protected final AbstractConfigurer getTemplateEngineConfigurer() {
 
 	private static final class TemplateEngineConfigurer extends AbstractConfigurer {
 
-		private TemplateEngine templateEngine = new MustacheTemplateEngine(
-				new StandardTemplateResourceResolver());
+		private TemplateEngine templateEngine;
 
 		@Override
 		public void apply(Map<String, Object> configuration,
 				RestDocumentationContext context) {
-			configuration.put(TemplateEngine.class.getName(), this.templateEngine);
+			TemplateEngine engineToUse = this.templateEngine;
+			if (engineToUse == null) {
+				SnippetConfiguration snippetConfiguration = (SnippetConfiguration) configuration
+						.get(SnippetConfiguration.class.getName());
+				engineToUse = new MustacheTemplateEngine(
+						new StandardTemplateResourceResolver(
+								snippetConfiguration.getFormat()));
+			}
+			configuration.put(TemplateEngine.class.getName(), engineToUse);
 		}
 
 		private void setTemplateEngine(TemplateEngine templateEngine) {
@@ -117,8 +124,12 @@ public void apply(Map<String, Object> configuration,
 				RestDocumentationContext context) {
 			WriterResolver resolverToUse = this.writerResolver;
 			if (resolverToUse == null) {
+				SnippetConfiguration snippetConfiguration = (SnippetConfiguration) configuration
+						.get(SnippetConfiguration.class.getName());
 				resolverToUse = new StandardWriterResolver(
-						new RestDocumentationContextPlaceholderResolver(context));
+						new RestDocumentationContextPlaceholderResolver(context),
+						snippetConfiguration.getEncoding(),
+						snippetConfiguration.getFormat());
 			}
 			configuration.put(WriterResolver.class.getName(), resolverToUse);
 		}

spring-restdocs-core/src/main/java/org/springframework/restdocs/config/SnippetConfiguration.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2014-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.restdocs.config;
+
+import org.springframework.restdocs.snippet.SnippetFormat;
+
+/**
+ * An encapsulation of the configuration for documentation snippets.
+ *
+ * @author Andy Wilkinson
+ */
+class SnippetConfiguration {
+
+	private final String encoding;
+
+	private final SnippetFormat format;
+
+	SnippetConfiguration(String encoding, SnippetFormat format) {
+		this.encoding = encoding;
+		this.format = format;
+	}
+
+	String getEncoding() {
+		return this.encoding;
+	}
+
+	SnippetFormat getFormat() {
+		return this.format;
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/config/SnippetConfigurer.java

@@ -24,7 +24,8 @@
 import org.springframework.restdocs.curl.CurlDocumentation;
 import org.springframework.restdocs.http.HttpDocumentation;
 import org.springframework.restdocs.snippet.Snippet;
-import org.springframework.restdocs.snippet.WriterResolver;
+import org.springframework.restdocs.snippet.SnippetFormat;
+import org.springframework.restdocs.snippet.SnippetFormats;
 
 /**
  * A configurer that can be used to configure the generated documentation snippets.
@@ -51,8 +52,18 @@ public abstract class SnippetConfigurer<P, T> extends AbstractNestedConfigurer<P
 	 */
 	public static final String DEFAULT_SNIPPET_ENCODING = "UTF-8";
 
+	/**
+	 * The default format for documentation snippets.
+	 *
+	 * @see #withFormat(SnippetFormat)
+	 */
+	public static final SnippetFormat DEFAULT_SNIPPET_FORMAT = SnippetFormats
+			.asciidoctor();
+
 	private String snippetEncoding = DEFAULT_SNIPPET_ENCODING;
 
+	private SnippetFormat snippetFormat = DEFAULT_SNIPPET_FORMAT;
+
 	/**
 	 * Creates a new {@code SnippetConfigurer} with the given {@code parent}.
 	 *
@@ -64,8 +75,8 @@ protected SnippetConfigurer(P parent) {
 
 	@Override
 	public void apply(Map<String, Object> configuration, RestDocumentationContext context) {
-		((WriterResolver) configuration.get(WriterResolver.class.getName()))
-				.setEncoding(this.snippetEncoding);
+		configuration.put(SnippetConfiguration.class.getName(), new SnippetConfiguration(
+				this.snippetEncoding, this.snippetFormat));
 		configuration.put(ATTRIBUTE_DEFAULT_SNIPPETS, this.defaultSnippets);
 	}
 
@@ -93,4 +104,17 @@ public T withDefaults(Snippet... defaultSnippets) {
 		this.defaultSnippets = Arrays.asList(defaultSnippets);
 		return (T) this;
 	}
+
+	/**
+	 * Configures the format of the documentation snippets.
+	 *
+	 * @param format the snippet format
+	 * @return {@code this}
+	 */
+	@SuppressWarnings("unchecked")
+	public T withFormat(SnippetFormat format) {
+		this.snippetFormat = format;
+		return (T) this;
+	}
+
 }