Allow custom snippet templates to be provided for multiple snippet formats

[wilkinsona]

At the moment in 1.1, a snippet template can be overridden by providing a classpath resource like org/springframework/restdocs/templates/${name}.snippet. If this snippet isn't found the default template for the current format is loaded from org/springframework/restdocs/templates/${formatId}/${name}.snippet. If a user wants to provide different overrides for different snippet formats they have to rely on the ordering of the classpath to get their template in org/springframework/restdocs/templates/${formatId}/ to appear before the default. This isn't user friendly.

The default templates for a particular format should be renamed to make it clear that they are the default and to allow them to be easily overridden. When resolving a template, the search order would then be:

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

2 is provided largely for backwards compatibility with 1.0.

/cc @andreasevers

[andreasevers]

Great, thanks for creating the issue for me :)

What would a format be in your explanation? I would suppose Json or Asciidoc?

In that case, would it be possible to have one test class generating Json snippets while another test class generates regular Asciidoc snippets?

[wilkinsona]

What would a format be in your explanation? I would suppose Json or Asciidoc?

Yes. There's a new TemplateFormat interface in 1.1 with two implementations; one for Asciidoctor and one for Markdown. Asciidoctor is the default. You could easily create your own for JSON.

In that case, would it be possible to have one test class generating Json snippets while another test class generates regular Asciidoc snippets?

Yes. You can configure the format when you're building the MockMvc instance (or the REST Assured RequestSpecification). It'd typically be configured per test class but you could configure it per test method if you wanted to.

[andreasevers]

Wow awesome! I was planning on giving this a go in a pull request but you beat me to it :D
Thanks a bunch!