Provide a Gradle plugin that applies REST Docs' configuration conventions

[wilkinsona]

When you use REST Docs with Gradle there are a few things that need to be configured:

1. snippetsDir extra property
2. Additional output directory on the test task that points to the snippets directory

When you're also using Asciidoctor the following also needs to be configured:

1. spring-restdocs-asciidoctor extension
2. Additional input directory on the asciidoctor task that points to the snippets directory
3. A dependency on the test task from the asciidoctor task

This configuration could be encapsulated in a plugin that applies these conventions, or a variant of them, automatically.

[jnizet]

Here are my comments on this issue.

First, I agree that having a plugin would be nice.

Regarding the plugin, my main fear is that it is too opinionated (or not flexible enough, i.e. not allowing to change its opinions):

• the generated html document should not be included in the generated jar/war by default (but we agree on that)
• I generally use dedicated tests, additional to the regular unit/integration tests, to generate the rest documentation, and these tests are run by a custom docTest task. So having a dependency on the test task from the asciidoctor task wouldn't work for this scenario (unless it can be customized somehow). Having separate tests allow them to be written later than the regular tests, to be focused on a more realistic scenario than the regular tests, and on the documentation rather than the correctness of the code. Since those documentation tests take some time to run and since the correctness of the code is already tested by other regular tests, using a separate test task makes running the regular tests faster. I suspect other people do this, or make a distinction between unit tests and integration tests.

I also wonder if spring rest docs shouldn't create its own task rather than using the the default asciidoctor task created by the asciidoctor plugin. Here's why I think it could be a good idea:

• it could react to the presence of, or add if it's missing, the base org.asciidoctor.jvm.base plugin rather than using the higher-level org.asciidoctor.jvm.convert plugin which creates the default asciidoctor task
• the task could have a better name (restDoc, rather than the generic asciidoctor)
• the task could have options (like the output directory, the default asciidoctorj options, etc.) that don't contradict with the default documented asciidoctor task options, making things less confusing for the user
• it wouldn't prevent users from using the default asciidoctor task in their build for something else than the rest documentation