我是Spring REST Docs的新手,并使用最新的1.2.1.Release。我有工作RESTful控制器,我有一堆工作测试。现在我正在介绍文档方面,以便为即将登场的新开发人员记录这些文档。Spring REST Docs生成空索引文件
我已经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>
而且,我有工作,测试和下/目标我看到用几个* .adoc文件创建的一些目录。这很棒。
我有一个/src/main/asciidoc/index.adoc创建,当我做我的构建它是成功的。 index.adoc文件中没有任何内容,是否必须存在? 因此,一个成功的构建之后,我得到很多 “ADOC” 下的文件:
/MyApp的平台-WS /目标/生成-片段
我也得到一个文件下 “的index.html”:/ MYAPP -platform-ws/target/generated-docs 但是里面没有任何东西......
我有几个其他控制器,每个控制器都有几个我将要记录的方法。这很好。但是,我想找到一些方法,我可以创建多个adoc文件的多个html文件。
Spring REST Docs对我来说确实是新的,我只是想了很多新东西,所以我可以将它发布到我的团队。
任何帮助将不胜感激!谢谢!
===============更新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>
是的,我必须包括版本,因为否则我会得到一个错误,这是不存在的,但它仍然是一个成功的构建。但是,现在我的测试都不会运行。
我也改变了我的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[]
所以,因为测试没有运行,它不添加这些文件。 我也怀疑'response-headers.adoc'也没有被生成。 测试运行时,我得到了片段。
我想我会在正确的轨道上,如果我可以再次运行测试。我根本没有跳过测试。
===============更新2.0 =================
我改变了万无一失的插件实际工作与测试我有:
<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。