Question

我是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>

并且，我有测试工作，在/目标下我看到一些目录是用几个* .adoc文件创建的。哪个好。

我确实创建了/src/main/asciidoc/index.adoc，当我进行构建时，它是成功的。 index.adoc文件中没有任何内容，是否必须存在？因此，在成功构建之后，我会在下面获得大量“adoc”文件：
/ MyApp的平台-WS /目标/生成-片段

我还在/ 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'。当测试运行时，我得到了片段。

如果我能让测试再次运行，我想我会走上正轨。我根本没有跳过测试。

=============== UPDATE 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。

Answer 1

如上所述的实验后，我终于开始工作了。我只需要正确的配置，最后它的工作原理。我现在创建了index.adoc文件，并创建了一个用内容创建的index.html文件。

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

Spring REST Docs生成空索引文件

1 个答案: