Open wilkinsona opened 5 years ago
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):
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:
org.asciidoctor.jvm.base
plugin rather than using the higher-level org.asciidoctor.jvm.convert
plugin which creates the default asciidoctor task restDoc
, rather than the generic asciidoctor
)
When you use REST Docs with Gradle there are a few things that need to be configured:
snippetsDir
extra propertytest
task that points to the snippets directoryWhen you're also using Asciidoctor the following also needs to be configured:
spring-restdocs-asciidoctor
extensionasciidoctor
task that points to the snippets directorytest
task from theasciidoctor
taskThis configuration could be encapsulated in a plugin that applies these conventions, or a variant of them, automatically.