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

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[]
+	}
+
+}