Allow custom templates to be provided for a specific template format

Previously, custom snippet templates were loaded from
org/springframework/restdocs/templates and the default templates were
loaded from org/springframework/restdocs/templates/{$formatId}.
Without relying on the ordering of the classpath, this made it
impossible to provide a custom template for a specific format.

This commit updates the locations that are checked for snippet
templates. The following locations are now checked in order:

1. org/springframework/restdocs/templates/${formatId}/${name}.snippet
2. org/springframework/restdocs/templates/${name}.snippet
3. org/springframework/restdocs/templates/${formatId}/default-${name}.snippet

The second location is provided largely for backwards compatibility
with 1.0. Users are expected to use the first location to provide
any custom templates, with Spring REST Docs provided templates for
all of the built-in snippets in the third location.

Closes gh-196
Closes gh-197

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -627,10 +627,14 @@ generated snippets.
 templates] are provided for each of the snippets that Spring REST Docs can produce. To
 customize a snippet's content, you can provide your own template.
 
-Templates are loaded from the classpath in the `org.springframework.restdocs.templates`
-package and each template is named after the snippet that it will produce. For example, to
+Templates are loaded from the classpath from an `org.springframework.restdocs.templates`
+subpackage. The name of the subpackage is determined by the ID of the template format
+that is in use. The default template format, Asciidoctor, has the ID `asciidoctor` so
+snippets are loaded from `org.springframework.restdocs.templates.asciidoctor`. Each
+template is named after the snippet that it will produce. For example, to
 override the template for the `curl-request.adoc` snippet, create a template named
-`curl-request.snippet` in `src/test/resources/org/springframework/restdocs/templates`.
+`curl-request.snippet` in
+`src/test/resources/org/springframework/restdocs/templates/asciidoctor`.
 
 
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/StandardTemplateResourceResolver.java

@@ -22,12 +22,20 @@ import org.springframework.core.io.Resource;
 /**
  * Standard implementation of {@link TemplateResourceResolver}.
  * <p>
- * Templates are resolved by looking for a resource on the classpath named
- * {@code org/springframework/restdocs/templates/&#123;name&#125;.snippet}. If no such
- * resource exists an attempt is made to return a default resource that is appropriate for
- * the configured snippet format.
+ * Templates are resolved by looking for resources on the classpath. The following
+ * locations are checked in order:
+ * <ol>
+ * <li>
+ * <code>org/springframework/restdocs/templates/${templateFormatId}/${name}.snippet</code>
+ * </li>
+ * <li><code>org/springframework/restdocs/templates/${name}.snippet</code></li>
+ * <li>
+ * <code>org/springframework/restdocs/templates/${templateFormatId}/default-${name}.snippet</code>
+ * </li>
+ * </ol>
  *
  * @author Andy Wilkinson
+ * @see TemplateFormat#getId()
  */
 public class StandardTemplateResourceResolver implements TemplateResourceResolver {
 
@@ -57,18 +65,37 @@ public class StandardTemplateResourceResolver implements TemplateResourceResolve
 
 	@Override
 	public Resource resolveTemplateResource(String name) {
-		ClassPathResource classPathResource = new ClassPathResource(
-				"org/springframework/restdocs/templates/" + name + ".snippet");
-		if (!classPathResource.exists()) {
-			classPathResource = new ClassPathResource(
-					"org/springframework/restdocs/templates/"
-							+ this.templateFormat.getId() + "/" + name + ".snippet");
-			if (!classPathResource.exists()) {
-				throw new IllegalStateException("Template named '" + name
-						+ "' could not be resolved");
-			}
+		Resource formatSpecificCustomTemplate = getFormatSpecificCustomTemplate(name);
+		if (formatSpecificCustomTemplate.exists()) {
+			return formatSpecificCustomTemplate;
 		}
-		return classPathResource;
+		Resource customTemplate = getCustomTemplate(name);
+		if (customTemplate.exists()) {
+			return customTemplate;
+		}
+		Resource defaultTemplate = getDefaultTemplate(name);
+		if (defaultTemplate.exists()) {
+			return defaultTemplate;
+		}
+		throw new IllegalStateException("Template named '" + name
+				+ "' could not be resolved");
+	}
+
+	private Resource getFormatSpecificCustomTemplate(String name) {
+		return new ClassPathResource(String.format(
+				"org/springframework/restdocs/templates/%s/%s.snippet",
+				this.templateFormat.getId(), name));
+	}
+
+	private Resource getCustomTemplate(String name) {
+		return new ClassPathResource(String.format(
+				"org/springframework/restdocs/templates/%s.snippet", name));
+	}
+
+	private Resource getDefaultTemplate(String name) {
+		return new ClassPathResource(String.format(
+				"org/springframework/restdocs/templates/%s/default-%s.snippet",
+				this.templateFormat.getId(), name));
 	}
 
 }

spring-restdocs-core/src/test/java/org/springframework/restdocs/templates/StandardTemplateResourceResolverTests.java

@@ -47,29 +47,17 @@ public class StandardTemplateResourceResolverTests {
 	private final TestClassLoader classLoader = new TestClassLoader();
 
 	@Test
-	public void customSnippetResolution() throws Exception {
-		this.classLoader.addResource(
-				"org/springframework/restdocs/templates/test.snippet", getClass()
-						.getResource("test.snippet"));
-		Resource snippet = doWithThreadContextClassLoader(this.classLoader,
-				new Callable<Resource>() {
-
-					@Override
-					public Resource call() {
-						return StandardTemplateResourceResolverTests.this.resolver
-								.resolveTemplateResource("test");
-					}
-
-				});
-
-		assertThat(snippet.getURL(), is(equalTo(getClass().getResource("test.snippet"))));
-	}
-
-	@Test
-	public void fallsBackToDefaultSnippet() throws Exception {
+	public void formatSpecificCustomSnippetHasHighestPrecedence() throws Exception {
 		this.classLoader.addResource(
 				"org/springframework/restdocs/templates/asciidoctor/test.snippet",
-				getClass().getResource("test.snippet"));
+				getClass().getResource("test-format-specific-custom.snippet"));
+		this.classLoader.addResource(
+				"org/springframework/restdocs/templates/test.snippet", getClass()
+						.getResource("test-custom.snippet"));
+		this.classLoader
+				.addResource(
+						"org/springframework/restdocs/templates/asciidoctor/default-test.snippet",
+						getClass().getResource("test-default.snippet"));
 		Resource snippet = doWithThreadContextClassLoader(this.classLoader,
 				new Callable<Resource>() {
 
@@ -81,11 +69,59 @@ public class StandardTemplateResourceResolverTests {
 
 				});
 
-		assertThat(snippet.getURL(), is(equalTo(getClass().getResource("test.snippet"))));
+		assertThat(
+				snippet.getURL(),
+				is(equalTo(getClass().getResource("test-format-specific-custom.snippet"))));
 	}
 
 	@Test
-	public void failsIfCustomAndDefaultSnippetDoNotExist() throws Exception {
+	public void generalCustomSnippetIsUsedInAbsenceOfFormatSpecificCustomSnippet()
+			throws Exception {
+		this.classLoader.addResource(
+				"org/springframework/restdocs/templates/test.snippet", getClass()
+						.getResource("test-custom.snippet"));
+		this.classLoader
+				.addResource(
+						"org/springframework/restdocs/templates/asciidoctor/default-test.snippet",
+						getClass().getResource("test-default.snippet"));
+		Resource snippet = doWithThreadContextClassLoader(this.classLoader,
+				new Callable<Resource>() {
+
+					@Override
+					public Resource call() {
+						return StandardTemplateResourceResolverTests.this.resolver
+								.resolveTemplateResource("test");
+					}
+
+				});
+
+		assertThat(snippet.getURL(),
+				is(equalTo(getClass().getResource("test-custom.snippet"))));
+	}
+
+	@Test
+	public void defaultSnippetIsUsedInAbsenceOfCustomSnippets() throws Exception {
+		this.classLoader
+				.addResource(
+						"org/springframework/restdocs/templates/asciidoctor/default-test.snippet",
+						getClass().getResource("test-default.snippet"));
+		Resource snippet = doWithThreadContextClassLoader(this.classLoader,
+				new Callable<Resource>() {
+
+					@Override
+					public Resource call() {
+						return StandardTemplateResourceResolverTests.this.resolver
+								.resolveTemplateResource("test");
+					}
+
+				});
+
+		assertThat(snippet.getURL(),
+				is(equalTo(getClass().getResource("test-default.snippet"))));
+	}
+
+	@Test
+	public void failsIfCustomAndDefaultSnippetsDoNotExist() throws Exception {
 		this.thrown.expect(IllegalStateException.class);
 		this.thrown.expectMessage(equalTo("Template named 'test' could not be resolved"));
 		doWithThreadContextClassLoader(this.classLoader, new Callable<Resource>() {