0

我是 Spring REST Docs 的新手并使用最新的 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

我还在：/myapp-platform-ws/target/generated-docs 下获得了一个文件“index.html”但是里面什么都没有......

我还有其他几个控制器，每个控制器都有几个我将记录的方法。这一切都很好。但是，我想找到一些方法，可以为创建的各种 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 =================

我更改了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。

4

1 回答 1

0

经过上面详细的实验，我终于让它工作了。我只需要正确配置，最后它就可以工作了。我现在创建了 index.adoc 文件和一个 index.html 文件，其中包含内容。

我现在，只需要更多地学习 AsciiDoctor，我可以更新所有 POSTS 和 PUT 以及 GET 的 index.adoc。

于 2017-08-21T19:32:51.553 回答