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

Polish contribution and rework to use default attribute rather than macro

Browse Source 
Rather than introducing a custom macro, this commit opts to implicitly
configure the snippets attribute instead. The attribute is configured
will the path into which snippets are generated, relative to the
directory that contains the Asciidoctor document that is being
rendered.

The samples and documentation have been updated to use the new
spring-restdocs-asciidoctor module and the implicitly configured
snippets attribute.

Closes gh-297
This commit is contained in:
Andy Wilkinson
2016-10-21 11:19:06 +01:00
parent 3ac4a1acad
commit 319bd139fc
31 changed files with 348 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
build.gradle
View File

@@ -67,6 +67,7 @@ subprojects {
dependency 'javax.servlet:javax.servlet-api:3.1.0'
dependency 'javax.validation:validation-api:1.1.0.Final'
dependency 'junit:junit:4.12'
dependency 'org.asciidoctor:asciidoctorj:1.5.3.1'
dependency 'org.hamcrest:hamcrest-core:1.3'
dependency 'org.hamcrest:hamcrest-library:1.3'
dependency 'org.hibernate:hibernate-validator:5.2.2.Final'

1
config/checkstyle/checkstyle-suppressions.xml
View File

@@ -5,5 +5,4 @@
<suppressions>
<suppress files="[\\/]src[\\/]test[\\/]java[\\/]" checks="JavadocVariable" />
<suppress files="[\\/]src[\\/]test[\\/]java[\\/]" checks="JavadocMethod" />
<suppress files="RestDocsSnippetBlockMacro\.java" checks="RedundantModifier" />
</suppressions>

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

@@ -94,13 +94,9 @@ the configuration are described below.
<scope>test</scope>
</dependency>
<properties> <2>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
<build>
<plugins>
<plugin> <3>
<plugin> <2>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
@@ -109,26 +105,30 @@ the configuration are described below.
</includes>
</configuration>
</plugin>
<plugin> <4>
<plugin> <3>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.2</version>
<version>1.5.3</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase> <6>
<phase>prepare-package</phase> <4>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<snippets>${snippetsDirectory}</snippets> <5>
</attributes>
</configuration>
</execution>
</executions>
<dependencies>
<dependency> <5>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-asciidoctor</artifactId>
<version>{project-version}</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
@@ -136,49 +136,50 @@ the configuration are described below.
<1> Add a dependency on `spring-restdocs-mockmvc` in the `test` scope. If you want to use
REST Assured rather than MockMvc, add a dependency on `spring-restdocs-restassured`
instead.
<2> Configure a property to define the output location for generated snippets.
<3> Add the SureFire plugin and configure it to include files whose names end with
<2> Add the SureFire plugin and configure it to include files whose names end with
`Documentation.java`.
<4> Add the Asciidoctor plugin
<5> Define an attribute named `snippets` that can be used when including the generated
snippets in your documentation.
<6> Using `prepare-package` allows the documentation to be
<3> Add the Asciidoctor plugin.
<4> Using `prepare-package` allows the documentation to be
<<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`.
[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"]
.Gradle
----
plugins { <1>
id "org.asciidoctor.convert" version "1.5.2"
id "org.asciidoctor.convert" version "1.5.3"
}
dependencies { <2>
testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}'
dependencies {
asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' <2>
testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' <3>
}
ext { <3>
ext { <4>
snippetsDir = file('build/generated-snippets')
}
test { <4>
test { <5>
outputs.dir snippetsDir
}
asciidoctor { <5>
attributes 'snippets': snippetsDir <6>
asciidoctor { <6>
inputs.dir snippetsDir <7>
dependsOn test <8>
}
----
<1> Apply the Asciidoctor plugin.
<2> Add a dependency on `spring-restdocs-mockmvc` in the `testCompile` configuration. If
<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`.
<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.
<3> Configure a property to define the output location for generated snippets.
<4> Configure the `test` task to add the snippets directory as an output.
<5> Configure the `asciidoctor` task
<6> Define an attribute named `snippets` that can be used when including the generated
snippets in your documentation.
<4> Configure a property to define the output location for generated snippets.
<5> Configure the `test` task to add the snippets directory as an output.
<6> Configure the `asciidoctor` task
<7> Configure the snippets directory as an input.
<8> Make the task depend on the test task so that the tests are run before the
documentation is created.
@@ -271,28 +272,38 @@ are also supported although slightly more setup is required.
===== Setting up your JUnit tests
When using JUnit, the first step in generating documentation snippets is to declare a
`public` `JUnitRestDocumentation` field that's annotated as a JUnit `@Rule`. The
`JUnitRestDocumentation` rule is configured with the output directory into which generated
snippets should be written. This output directory should match the snippets directory that
you have configured in your `build.gradle` or `pom.xml` file.
`public` `JUnitRestDocumentation` field that's annotated as a JUnit `@Rule`.
For Maven (`pom.xml`) that will typically be `target/generated-snippets` and for
Gradle (`build.gradle`) it will typically be `build/generated-snippets`:
[source,java,indent=0,role="primary"]
.Maven
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation =
new JUnitRestDocumentation("target/generated-snippets");
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
----
[source,java,indent=0,role="secondary"]
.Gradle
By default, the `JUnitRestDocumentation` rule is automatically configured with an output
directory based on your project's build tool:
[cols="2,5"]
|===
| Build tool | Output directory
| Maven
| `target/generated-snippets`
| Gradle
| `build/generated-snippets`
|===
The default can be overridden by providing an output directory when creating the
`JUnitRestDocumentation` instance:
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation =
new JUnitRestDocumentation("build/generated-snippets");
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
----
Next, provide an `@Before` method to configure MockMvc or REST Assured:
@@ -331,18 +342,9 @@ illustrates the approach.
The first difference is that `ManualRestDocumentation` should be used in place of
`JUnitRestDocumentation` and there's no need for the `@Rule` annotation:
[source,java,indent=0,role="primary"]
.Maven
[source,java,indent=0]
----
private ManualRestDocumentation restDocumentation =
new ManualRestDocumentation("target/generated-snippets");
----
[source,java,indent=0,role="secondary"]
.Gradle
----
private ManualRestDocumentation restDocumentation =
new ManualRestDocumentation("build/generated-snippets");
private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();
----
Secondly, `ManualRestDocumentation.beforeTest(Class, String)`
@@ -441,7 +443,8 @@ the resulting HTML files depends on whether you are using Maven or Gradle:
The generated snippets can then be included in the manually created Asciidoctor file from
above using the
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include macro].
The `snippets` attribute specified in the <<getting-started-build-configuration, build
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:
[source,adoc,indent=0]

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

@@ -17,10 +17,11 @@ relevant to Spring REST Docs.
[[working-with-asciidoctor-including-snippets]]
=== Including snippets
The http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
The http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
macro] is used to include generated snippets in your documentation. The `snippets`
attribute specified in the <<getting-started-build-configuration, build configuration>>
can be used to reference the snippets output directory, for example:
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:
[source,adoc,indent=0]
----

2
samples/rest-assured/build.gradle
View File

@@ -37,6 +37,7 @@ dependencies {
compile 'org.springframework.boot:spring-boot-starter-web'
testCompile 'org.springframework.boot:spring-boot-starter-test'
testCompile "org.springframework.restdocs:spring-restdocs-restassured:${project.ext['spring-restdocs.version']}"
asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"
}
test {
@@ -44,7 +45,6 @@ test {
}
asciidoctor {
attributes 'snippets': snippetsDir
inputs.dir snippetsDir
dependsOn test
}

5
samples/rest-notes-grails/.gitignore vendored
View File

@@ -11,7 +11,4 @@ classes/
.settings
.classpath
gradlew*
gradle/wrapper
src/docs/generated-snippets
gradle/wrapper

13
samples/rest-notes-grails/build.gradle
View File

@@ -44,6 +44,7 @@ repositories {
dependencyManagement {
dependencies {
dependency "org.springframework.restdocs:spring-restdocs-restassured:$restDocsVersion"
dependency "org.springframework.restdocs:spring-restdocs-asciidoctor:$restDocsVersion"
}
imports {
mavenBom "org.grails:grails-bom:$grailsVersion"
@@ -53,6 +54,8 @@ dependencyManagement {
}
dependencies {
asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor"
compile "org.springframework.boot:spring-boot-starter-logging"
compile "org.springframework.boot:spring-boot-starter-actuator"
compile "org.springframework.boot:spring-boot-autoconfigure"
@@ -85,24 +88,16 @@ task wrapper(type: Wrapper) {
}
ext {
snippetsDir = file('src/docs/generated-snippets')
}
task cleanTempDirs(type: Delete) {
delete fileTree(dir: 'src/docs/generated-snippets')
snippetsDir = file('build/generated-snippets')
}
test {
dependsOn cleanTempDirs
outputs.dir snippetsDir
}
asciidoctor {
dependsOn integrationTest
inputs.dir snippetsDir
sourceDir = file('src/docs')
separateOutputDirs = false
attributes 'snippets': snippetsDir
}
build.dependsOn asciidoctor

0
samples/rest-notes-grails/src/docs/index.adoc → samples/rest-notes-grails/src/docs/asciidoc/index.adoc
View File

2
samples/rest-notes-grails/src/integration-test/groovy/com/example/ApiDocumentationSpec.groovy
View File

@@ -45,7 +45,7 @@ import spock.lang.Specification
class ApiDocumentationSpec extends Specification {
@Rule
JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation('src/docs/generated-snippets')
JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation()
@Value('${local.server.port}')
Integer serverPort

10
samples/rest-notes-spring-data-rest/pom.xml
View File

@@ -84,12 +84,16 @@
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<snippets>${project.build.directory}/generated-snippets</snippets>
</attributes>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-asciidoctor</artifactId>
<version>${spring-restdocs.version}</version>
</dependency>
</dependencies>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>

3
samples/rest-notes-spring-hateoas/build.gradle
View File

@@ -34,6 +34,8 @@ ext['spring.version']='4.3.1.RELEASE'
ext['spring-restdocs.version'] = '1.2.0.BUILD-SNAPSHOT'
dependencies {
asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"
compile 'org.springframework.boot:spring-boot-starter-data-jpa'
compile 'org.springframework.boot:spring-boot-starter-hateoas'
@@ -50,7 +52,6 @@ test {
}
asciidoctor {
attributes 'snippets': snippetsDir
inputs.dir snippetsDir
dependsOn test
}

4
samples/testng/build.gradle
View File

@@ -34,7 +34,10 @@ ext['spring.version']='4.3.1.RELEASE'
ext['spring-restdocs.version'] = '1.2.0.BUILD-SNAPSHOT'
dependencies {
asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${project.ext['spring-restdocs.version']}"
compile 'org.springframework.boot:spring-boot-starter-web'
testCompile('org.springframework:spring-test') {
exclude group: 'junit', module: 'junit;'
}
@@ -48,7 +51,6 @@ test {
}
asciidoctor {
attributes 'snippets': snippetsDir
inputs.dir snippetsDir
dependsOn test
}

2
settings.gradle
View File

@@ -1,7 +1,7 @@
rootProject.name = 'spring-restdocs'
include 'docs'
include 'spring-restdocs-asciidoctor-extensions'
include 'spring-restdocs-asciidoctor'
include 'spring-restdocs-core'
include 'spring-restdocs-mockmvc'
include 'spring-restdocs-restassured'

6
spring-restdocs-asciidoctor-extensions/build.gradle
View File

@@ -1,6 +0,0 @@
description = 'Spring REST Docs Asciidoctor Extensions'
dependencies {
compile 'org.asciidoctor:asciidoctorj:1.5.2'
optional 'junit:junit'
}

66
spring-restdocs-asciidoctor-extensions/src/main/java/org/springframework/restdocs/asciidoctor/extensions/RestDocsSnippetBlockMacro.java
View File

@@ -1,66 +0,0 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor.extensions;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Map;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.OptionsBuilder;
import org.asciidoctor.ast.AbstractBlock;
import org.asciidoctor.extension.BlockMacroProcessor;
/**
* Block macro to include snippets generated by Spring Rest Docs in a convenient way.
* Defaults to <i>build</i> (gradle) or <i>target</i> directory to look for the generated-snippets folder and its content.
*
* @author Gerrit Meier
*/
class RestDocsSnippetBlockMacro extends BlockMacroProcessor {
private static final String GENERATED_SNIPPETS_PATH = "generated-snippets";
private static final String MAVEN_TARGET_PATH = "target" + File.separator + GENERATED_SNIPPETS_PATH;
private static final String GRADLE_BUILD_PATH = "build" + File.separator + GENERATED_SNIPPETS_PATH;
private static final String MAVEN_POM = "pom.xml";
public RestDocsSnippetBlockMacro(String macroName, Map<String, Object> config) {
super(macroName, config);
}
@Override
protected Object process(AbstractBlock parent, String fileToInclude, Map<String, Object> attributes) {
String generatedSnippetPath = getDefaultOutputDirectory() + File.separator + fileToInclude;
// since 'pass' context does not convert the content, we have to do this manually
String convertedContent = Asciidoctor.Factory.create().convertFile(
new File(generatedSnippetPath),
OptionsBuilder.options().toFile(false).inPlace(false).get());
return createBlock(parent, "pass", convertedContent, attributes, getConfig());
}
private static String getDefaultOutputDirectory() {
String executingDirectory = Paths.get(".").toFile().getAbsolutePath();
if (Files.exists(Paths.get(MAVEN_POM))) {
return executingDirectory + File.separator + MAVEN_TARGET_PATH;
}
return executingDirectory + File.separator + GRADLE_BUILD_PATH;
}
}

1
spring-restdocs-asciidoctor-extensions/src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry
View File

@@ -1 +0,0 @@
org.springframework.restdocs.asciidoctor.extensions.RestDocsExtensionRegistry

54
spring-restdocs-asciidoctor-extensions/src/test/java/org/springframework/restdocs/asciidoctor/extensions/RestDocsSnippetBlockMacroTest.java
View File

@@ -1,54 +0,0 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor.extensions;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.Options;
import org.junit.Before;
import org.junit.Test;
import static org.hamcrest.CoreMatchers.equalTo;
import static org.junit.Assert.assertThat;
/**
* Tests for {@link RestDocsSnippetBlockMacro}.
*
* @author Gerrit Meier
*/
public class RestDocsSnippetBlockMacroTest {
@Before
public void prepareIncludeFiles() throws Exception {
Files.createDirectories(Paths.get("build/generated-snippets/"));
Files.copy(Paths.get("src/test/resources/rest_docs_macro.adoc"),
Paths.get("build/generated-snippets/rest_docs_macro.adoc"), StandardCopyOption.REPLACE_EXISTING);
}
@Test
public void replaceRestDocsSnippetBlockWithFile() {
Asciidoctor asciidoctor = Asciidoctor.Factory.create();
asciidoctor.javaExtensionRegistry().blockMacro("snippet", RestDocsSnippetBlockMacro.class);
assertThat(asciidoctor.convert("snippet::rest_docs_macro.adoc[]", new Options()),
equalTo("<div class=\"paragraph\">\n<p>test text</p>\n</div>"));
}
}

1
spring-restdocs-asciidoctor-extensions/src/test/resources/rest_docs_macro.adoc
View File

@@ -1 +0,0 @@
test text

7
spring-restdocs-asciidoctor/build.gradle Normal file
View File

@@ -0,0 +1,7 @@
description = 'Asciidoctor extensions for Spring REST Docs'
dependencies {
compileOnly 'org.asciidoctor:asciidoctorj'
testCompile 'junit:junit'
testCompile 'org.asciidoctor:asciidoctorj'
}

43
spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessor.java Normal file
View File

@@ -0,0 +1,43 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor;
import java.io.File;
import org.asciidoctor.ast.Document;
import org.asciidoctor.extension.Preprocessor;
import org.asciidoctor.extension.PreprocessorReader;
/**
* {@link Preprocessor} that sets defaults for REST Docs-related {@link Document}
* attributes.
*
* @author Andy Wilkinson
*/
final class DefaultAttributesPreprocessor extends Preprocessor {
private final SnippetsDirectoryResolver snippetsDirectoryResolver = new SnippetsDirectoryResolver(
new File("."));
@Override
public PreprocessorReader process(Document document, PreprocessorReader reader) {
document.setAttr("snippets", this.snippetsDirectoryResolver
.getSnippetsDirectory(document.getAttributes()), false);
return reader;
}
}

24
spring-restdocs-asciidoctor-extensions/src/main/java/org/springframework/restdocs/asciidoctor/extensions/RestDocsExtensionRegistry.java → spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/RestDocsExtensionRegistry.java
View File

@@ -14,32 +14,22 @@
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor.extensions;
package org.springframework.restdocs.asciidoctor;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.extension.spi.ExtensionRegistry;
/**
* ExtensionRegistry for the Spring Rest Docs macros to get registered
* in all projects that include this asciidoctor extension module.
* <p>
* Macros provided:
* <ul>
* <li>{@link RestDocsSnippetBlockMacro}</li>
* </ul>
* Asciidoctor {@link ExtensionRegistry} for Spring REST Docs.
*
* @author Gerrit Meier
* @author Andy Wilkinson
*/
public class RestDocsExtensionRegistry implements ExtensionRegistry {
/**
* the name that identifies the block macro in the asciidoctor document
* (e.g. <pre><b>snippet</b>::file_to_include[]</pre>)
*/
private static final String SNIPPET_BLOCK_NAME = "snippet";
public final class RestDocsExtensionRegistry implements ExtensionRegistry {
@Override
public void register(Asciidoctor asciidoctor) {
asciidoctor.javaExtensionRegistry().blockMacro(SNIPPET_BLOCK_NAME, RestDocsSnippetBlockMacro.class);
asciidoctor.javaExtensionRegistry()
.preprocessor(new DefaultAttributesPreprocessor());
}
}

58
spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolver.java Normal file
View File

@@ -0,0 +1,58 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor;
import java.io.File;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Map;
/**
* Resolves the directory from which snippets can be read for inclusion in an Asciidoctor
* document. The resolved directory is relative to the {@code docdir} of the Asciidoctor
* document that it being rendered.
*
* @author Andy Wilkinson
*/
class SnippetsDirectoryResolver {
private final File root;
SnippetsDirectoryResolver(File root) {
this.root = root;
}
File getSnippetsDirectory(Map<String, Object> attributes) {
if (new File(this.root, "pom.xml").exists()) {
return getMavenSnippetsDirectory(attributes);
}
return getGradleSnippetsDirectory(attributes);
}
private File getMavenSnippetsDirectory(Map<String, Object> attributes) {
Path rootPath = Paths.get(this.root.getAbsolutePath());
Path docDirPath = Paths.get((String) attributes.get("docdir"));
Path relativePath = docDirPath.relativize(rootPath);
return new File(relativePath.toFile(), "target/generated-snippets");
}
private File getGradleSnippetsDirectory(Map<String, Object> attributes) {
return new File((String) attributes.get("projectdir"),
"build/generated-snippets");
}
}

1
spring-restdocs-asciidoctor/src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry Normal file
View File

@@ -0,0 +1 @@
org.springframework.restdocs.asciidoctor.RestDocsExtensionRegistry

58
spring-restdocs-asciidoctor/src/test/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessorTests.java Normal file
View File

@@ -0,0 +1,58 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.Attributes;
import org.asciidoctor.Options;
import org.junit.Test;
import static org.hamcrest.CoreMatchers.containsString;
import static org.junit.Assert.assertThat;
/**
* Tests for {@link DefaultAttributesPreprocessor}.
*
* @author Andy Wilkinson
*/
public class DefaultAttributesPreprocessorTests {
@Test
public void snippetsAttributeIsSet() {
String converted = Asciidoctor.Factory.create().convert("{snippets}",
new Options());
assertThat(converted, containsString("build/generated-snippets"));
}
@Test
public void snippetsAttributeFromConvertArgumentIsNotOverridden() {
Options options = new Options();
options.setAttributes(new Attributes("snippets=custom"));
String converted = Asciidoctor.Factory.create().convert("{snippets}", options);
assertThat(converted, containsString("custom"));
}
@Test
public void snippetsAttributeFromDocumentPreambleIsNotOverridden() {
Options options = new Options();
options.setAttributes(new Attributes("snippets=custom"));
String converted = Asciidoctor.Factory.create()
.convert(":snippets: custom\n{snippets}", options);
assertThat(converted, containsString("custom"));
}
}

68
spring-restdocs-asciidoctor/src/test/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolverTests.java Normal file
View File

@@ -0,0 +1,68 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.asciidoctor;
import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import org.junit.Rule;
import org.junit.Test;
import org.junit.rules.TemporaryFolder;
import static org.hamcrest.CoreMatchers.equalTo;
import static org.hamcrest.CoreMatchers.is;
import static org.junit.Assert.assertThat;
/**
* Tests for {@link SnippetsDirectoryResolver}.
*
* @author Andy Wilkinson
*/
public class SnippetsDirectoryResolverTests {
@Rule
public TemporaryFolder temporaryFolder = new TemporaryFolder();
@Test
public void mavenProjectsUseTargetGeneratedSnippetsRelativeToDocDir()
throws IOException {
this.temporaryFolder.newFile("pom.xml");
Map<String, Object> attributes = new HashMap<>();
attributes.put("docdir",
new File(this.temporaryFolder.getRoot(), "src/main/asciidoc")
.getAbsolutePath());
File snippetsDirectory = new SnippetsDirectoryResolver(
this.temporaryFolder.getRoot()).getSnippetsDirectory(attributes);
assertThat(snippetsDirectory.isAbsolute(), is(false));
assertThat(snippetsDirectory,
equalTo(new File("../../../target/generated-snippets")));
}
@Test
public void gradleProjectsUseBuildGeneratedSnippetsBeneathProjectDir()
throws IOException {
Map<String, Object> attributes = new HashMap<>();
attributes.put("projectdir", "project/dir");
File snippetsDirectory = new SnippetsDirectoryResolver(
this.temporaryFolder.getRoot()).getSnippetsDirectory(attributes);
assertThat(snippetsDirectory,
equalTo(new File("project/dir/build/generated-snippets")));
}
}

4
spring-restdocs-asciidoctor/src/test/resources/sample-snippet.adoc Normal file
View File

@@ -0,0 +1,4 @@
[source,bash]
----
$ curl 'http://localhost:8080/' -i -H 'Accept: application/hal+json'
----

24
spring-restdocs-core/src/main/java/org/springframework/restdocs/ManualRestDocumentation.java
View File

@@ -17,8 +17,6 @@
package org.springframework.restdocs;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
/**
* {@code ManualRestDocumentation} is used to manually manage the
@@ -33,11 +31,6 @@ import java.nio.file.Paths;
*/
public final class ManualRestDocumentation implements RestDocumentationContextProvider {
private static final String GENERATED_SNIPPETS_PATH = "generated-snippets";
private static final String MAVEN_TARGET_PATH = "target" + File.separator + GENERATED_SNIPPETS_PATH;
private static final String GRADLE_BUILD_PATH = "build" + File.separator + GENERATED_SNIPPETS_PATH;
private static final String MAVEN_POM = "pom.xml";
private final File outputDirectory;
private RestDocumentationContext context;
@@ -57,7 +50,11 @@ public final class ManualRestDocumentation implements RestDocumentationContextPr
* @param outputDirectory the output directory
*/
public ManualRestDocumentation(String outputDirectory) {
this.outputDirectory = new File(outputDirectory);
this(new File(outputDirectory));
}
private ManualRestDocumentation(File outputDirectory) {
this.outputDirectory = outputDirectory;
}
/**
@@ -94,12 +91,11 @@ public final class ManualRestDocumentation implements RestDocumentationContextPr
return this.context;
}
private static String getDefaultOutputDirectory() {
String executingDirectory = Paths.get(".").toFile().getAbsolutePath();
if (Files.exists(Paths.get(MAVEN_POM))) {
return executingDirectory + File.separator + MAVEN_TARGET_PATH;
private static File getDefaultOutputDirectory() {
if (new File("pom.xml").exists()) {
return new File("target/generated-snippets");
}
return executingDirectory + File.separator + GRADLE_BUILD_PATH;
return new File("build/generated-snippets");
}
}

3
spring-restdocs-core/src/test/java/org/springframework/restdocs/config/RestDocumentationConfigurerTests.java
View File

@@ -195,7 +195,8 @@ public class RestDocumentationConfigurerTests {
}
private RestDocumentationContext createContext() {
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation("build");
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(
"build");
manualRestDocumentation.beforeTest(null, null);
RestDocumentationContext context = manualRestDocumentation.beforeOperation();
return context;

3
spring-restdocs-core/src/test/java/org/springframework/restdocs/snippet/RestDocumentationContextPlaceholderResolverTests.java
View File

@@ -83,7 +83,8 @@ public class RestDocumentationContextPlaceholderResolverTests {
}
private RestDocumentationContext createContext(String methodName) {
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation("build");
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(
"build");
manualRestDocumentation.beforeTest(getClass(), methodName);
RestDocumentationContext context = manualRestDocumentation.beforeOperation();
return context;

3
spring-restdocs-core/src/test/java/org/springframework/restdocs/snippet/StandardWriterResolverTests.java
View File

@@ -70,7 +70,8 @@ public class StandardWriterResolverTests {
}
private RestDocumentationContext createContext(String outputDir) {
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(outputDir);
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(
outputDir);
manualRestDocumentation.beforeTest(getClass(), null);
RestDocumentationContext context = manualRestDocumentation.beforeOperation();
return context;

3
spring-restdocs-core/src/test/java/org/springframework/restdocs/test/OperationBuilder.java
View File

@@ -123,7 +123,8 @@ public class OperationBuilder extends OperationTestRule {
}
private RestDocumentationContext createContext() {
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(this.outputDirectory.getAbsolutePath());
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(
this.outputDirectory.getAbsolutePath());
manualRestDocumentation.beforeTest(null, null);
RestDocumentationContext context = manualRestDocumentation.beforeOperation();
return context;