Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish “Provide a block macro for including an operation's snippets”

Browse Source 
- Copy snippets used in the tests in @BeforeClass rather than using
   Gradle so that the tests can be run easily in an IDE
 - Address problems in operation_block_macro.rb reported by Rubocop
 - Rename new test class to more closely match the name of the Ruby
   class that it’s testing
 - Gracefully handle a missing operation
 - Align behaviour when an operation or snippet is missing more closely
   with Asciidoctor’s behaviour when an include references a missing
   file
 - Use kebab-case rather than snake_case for new test resources
 - Update the documentation to describe the new macro

See gh-354
Closes gh-323
This commit is contained in:
Andy Wilkinson
2017-03-07 16:46:35 +00:00
parent 18b559a839
commit 826e0a5dec
15 changed files with 185 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/src/docs/asciidoc/getting-started.adoc
View File

@@ -143,7 +143,8 @@ the configuration are described below.
<<getting-started-build-configuration-maven-packaging, included in the package>>.
<5> Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin. This
will automatically configure the `snippets` attribute for use in your `.adoc` files to
point to `target/generated-snippets`.
point to `target/generated-snippets`. It will also allow you to use the `operation`
block macro.
[source,indent=0,subs="verbatim,attributes",role="secondary"]
.Gradle
@@ -173,7 +174,8 @@ the configuration are described below.
<1> Apply the Asciidoctor plugin.
<2> Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctor` configuration.
This will automatically configure the `snippets` attribute for use in your `.adoc`
files to point to `build/generated-snippets`.
files to point to `build/generated-snippets`. It will also allow you to use the
`operation` block macro.
<3> Add a dependency on `spring-restdocs-mockmvc` in the `testCompile` configuration. If
you want to use REST Assured rather than MockMvc, add a dependency on
`spring-restdocs-restassured` instead.

33
docs/src/docs/asciidoc/working-with-asciidoctor.adoc
View File

@@ -17,8 +17,39 @@ relevant to Spring REST Docs.
[[working-with-asciidoctor-including-snippets]]
=== Including snippets
[[working-with-asciidoctor-including-snippets-operation]]
==== Including multiple snippets for an operation
A macro named `operation` can be used to import all or some of the snippets that have
been generated for a specific operation. It is made available by including
`spring-restdocs-asciidoctor` in your project's <<getting-started-build-configuration,
build configuration>>.
The target of the macro is the name of the operation. The `snippets` attribute can be
used to select the snippets that should be included using a comma-separated list.
Each entry in the list should be the name of a snippet file, minus the `.adoc` suffix,
to include. For example, to include the curl, HTTP request and HTTP response snippets
for the index operation:
[source,indent=0]
----
operation::index[snippets=curl-request,http-request,http-response]
----
To include all of an operation's snippets, the `snippets` attribute can be omitted:
[source,indent=0]
----
operation::index[]
----
[[working-with-asciidoctor-including-snippets-individual]]
==== Including individual snippets
The http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
macro] is used to include generated snippets in your documentation. The `snippets`
macro] is used to include individual snippets in your documentation. The `snippets`
attribute that is automatically set by `spring-restdocs-asciidoctor` configured in the
<<getting-started-build-configuration, build configuration>> can be used to reference the
snippets output directory. For example: