Spring REST Docs 生成空索引文件
Spring REST Docs generates empty index file
我是 Spring REST 文档的新手，使用的是最新的 1.2.1.Release。我有工作 RESTful 控制器，我有一堆工作测试。现在我将介绍文档方面，以便为新加入的开发人员记录这些内容。
我的 pom.xml 配置如下：
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<version>1.2.1.RELEASE</version>
<scope>test</scope>
</dependency>
这里是构建插件所在的位置：
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
<build>
<outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>
<doCheck>false</doCheck>
<doUpdate>false</doUpdate>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
</manifest>
<manifestEntries>
<Git-Revision>${buildNumber}</Git-Revision>
</manifestEntries>
</archive>
<archiveClasses>true</archiveClasses>
<webResources>
<!-- in order to interpolate version from pom into appengine-web.xml -->
<resource>
<directory>${basedir}/src/main/webapp/WEB-INF</directory>
<filtering>true</filtering>
<targetPath>WEB-INF</targetPath>
</resource>
</webResources>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.5</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<snippets>${snippetsDirectory}</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory> ${project.build.outputDirectory}/static/docs
</outputDirectory>
<resources>
<resource>
<directory> ${project.build.directory}/generated-docs
</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
而且，我进行了一些测试，在 /target 下我看到一些目录是用几个 *.adoc 文件创建的。太棒了。
我确实创建了一个 /src/main/asciidoc/index.adoc，当我构建时它是成功的。 index.adoc文件里什么都没有，一定要有吗？
因此，在成功构建之后，我在以下位置获得了大量 "adoc" 文件：
/myapp-platform-ws/target/generated-snippets
我还得到一个文件 "index.html" 位于：/myapp-platform-ws/target/generated-docs
但是里面什么都没有....
我还有其他几个控制器，每个控制器都有几个我将记录的方法。这一切都很好。但是，我想找到一些方法，我可以为创建的各种 adoc 文件创建多个 html 文件。
Spring REST 文档对我来说真的很新，我只是尝试了很多新东西，以便我可以将其发布给我的团队。
如有任何帮助，我们将不胜感激！谢谢！
=============== 更新 1.0 =================
所以，我在 'asciidoctor' 插件之前添加了这个插件。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
</configuration>
</plugin>
是的，我必须包含该版本，否则我会收到一条错误消息，指出它不存在，但它仍然是一个成功的构建。但是，现在 none 我的测试将 运行.
我还更改了我的 index.adoc 以包括以下内容：
[[overview-headers]]
== Headers
Every response has the following header(s):
<h>Organizations</h>
include::{snippets}/orgs/response-headers.adoc[]
include::{snippets}/orgs/portal/response-headers.adoc[]
因此，由于测试未 运行ning，因此不会添加这些文件。
我还怀疑 'response-headers.adoc' 也没有生成。
当测试 运行ning 时，我正在获取代码片段。
我想如果我能再次接受测试 运行ning，我就会走上正轨。我根本没有跳过测试。
=============== 更新 2.0 =================
我更改了 surefire 插件以实际处理我的测试：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Test.java</include>
</includes>
</configuration>
</plugin>
因为我所有的测试，都以 /*Test.java
结尾
所以，这让我所有的测试都执行了。
由于收到 *.adoc 文件丢失的消息，我仔细检查了
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
设置正确，但我没有意识到它已被删除，所以我重新添加它，并且不再收到错误消息。
我不记得我是否提到过它，但我在 index.adoc 中添加了详细信息，然后我终于能够获得包含内容的生成 index.html。
我现在只需要更多地学习 AsciiDoctor，我可以更新所有 POSTS 和 PUT 以及 GET 的 index.adoc。
经过上面详述的实验，我终于让它工作了。我只需要正确配置，最后它就可以工作了。我现在创建了 index.adoc 个文件，并创建了 index.html 个包含内容的文件。
我现在只需要更多地学习 AsciiDoctor，我可以更新所有 POSTS 和 PUT 以及 GET 的 index.adoc。
我是 Spring REST 文档的新手，使用的是最新的 1.2.1.Release。我有工作 RESTful 控制器，我有一堆工作测试。现在我将介绍文档方面，以便为新加入的开发人员记录这些内容。
我的 pom.xml 配置如下：
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<version>1.2.1.RELEASE</version>
<scope>test</scope>
</dependency>
这里是构建插件所在的位置：
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
<build>
<outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>
<doCheck>false</doCheck>
<doUpdate>false</doUpdate>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
</manifest>
<manifestEntries>
<Git-Revision>${buildNumber}</Git-Revision>
</manifestEntries>
</archive>
<archiveClasses>true</archiveClasses>
<webResources>
<!-- in order to interpolate version from pom into appengine-web.xml -->
<resource>
<directory>${basedir}/src/main/webapp/WEB-INF</directory>
<filtering>true</filtering>
<targetPath>WEB-INF</targetPath>
</resource>
</webResources>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.5</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<snippets>${snippetsDirectory}</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory> ${project.build.outputDirectory}/static/docs
</outputDirectory>
<resources>
<resource>
<directory> ${project.build.directory}/generated-docs
</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
而且，我进行了一些测试，在 /target 下我看到一些目录是用几个 *.adoc 文件创建的。太棒了。
我确实创建了一个 /src/main/asciidoc/index.adoc，当我构建时它是成功的。 index.adoc文件里什么都没有，一定要有吗？
因此，在成功构建之后，我在以下位置获得了大量 "adoc" 文件：
/myapp-platform-ws/target/generated-snippets
我还得到一个文件 "index.html" 位于：/myapp-platform-ws/target/generated-docs 但是里面什么都没有....
我还有其他几个控制器，每个控制器都有几个我将记录的方法。这一切都很好。但是，我想找到一些方法，我可以为创建的各种 adoc 文件创建多个 html 文件。
Spring REST 文档对我来说真的很新，我只是尝试了很多新东西，以便我可以将其发布给我的团队。
如有任何帮助，我们将不胜感激！谢谢！
=============== 更新 1.0 =================
所以，我在 'asciidoctor' 插件之前添加了这个插件。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
</configuration>
</plugin>
是的，我必须包含该版本，否则我会收到一条错误消息，指出它不存在，但它仍然是一个成功的构建。但是，现在 none 我的测试将 运行.
我还更改了我的 index.adoc 以包括以下内容：
[[overview-headers]]
== Headers
Every response has the following header(s):
<h>Organizations</h>
include::{snippets}/orgs/response-headers.adoc[]
include::{snippets}/orgs/portal/response-headers.adoc[]
因此，由于测试未 运行ning，因此不会添加这些文件。 我还怀疑 'response-headers.adoc' 也没有生成。 当测试 运行ning 时，我正在获取代码片段。
我想如果我能再次接受测试 运行ning，我就会走上正轨。我根本没有跳过测试。
=============== 更新 2.0 =================
我更改了 surefire 插件以实际处理我的测试：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Test.java</include>
</includes>
</configuration>
</plugin>
因为我所有的测试，都以 /*Test.java
结尾
所以，这让我所有的测试都执行了。
由于收到 *.adoc 文件丢失的消息，我仔细检查了
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
设置正确，但我没有意识到它已被删除，所以我重新添加它，并且不再收到错误消息。
我不记得我是否提到过它，但我在 index.adoc 中添加了详细信息，然后我终于能够获得包含内容的生成 index.html。
我现在只需要更多地学习 AsciiDoctor，我可以更新所有 POSTS 和 PUT 以及 GET 的 index.adoc。
经过上面详述的实验，我终于让它工作了。我只需要正确配置，最后它就可以工作了。我现在创建了 index.adoc 个文件，并创建了 index.html 个包含内容的文件。
我现在只需要更多地学习 AsciiDoctor，我可以更新所有 POSTS 和 PUT 以及 GET 的 index.adoc。