search

spring-projects / spring-restdocs

Test-driven documentation for RESTful services
https://spring.io/projects/spring-restdocs
Apache License 2.0
1.16k stars 736 forks source link

Allow custom snippet templates to be provided for multiple snippet formats #197

Closed wilkinsona closed 8 years ago

wilkinsona commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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