CODEWITHSUNDEEP
javarestmavenspring-restdocs
tjholmes66
tjholmes66

Reputation: 1998

Spring REST Docs generates empty index file

I am new to Spring REST Docs and using the latest 1.2.1.Release. I have working RESTful controllers, and I have a bunch of working tests. Now I am introducing the docs aspect to get these documented for new developers coming on board.

I have the pom.xml configured as such:

   <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <version>1.2.1.RELEASE</version>
        <scope>test</scope>
    </dependency>

and here is where the build plugins are:

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

And, I have tests that work and under /target I was seeing some directories created with several *.adoc files. Which is great.

I do have a /src/main/asciidoc/index.adoc created, and when I do my build it is successful. There is nothing in the index.adoc file, does there have to be? So, after a successful build, I get plenty of "adoc" files under:
/myapp-platform-ws/target/generated-snippets

I also get a file "index.html" under: /myapp-platform-ws/target/generated-docs But there is nothing in it ....

I have several other controllers, each with several methods that I will be documenting. This is all fine. However, I'd like to find some method where I can have multiple html files for the various adoc files created.

Spring REST Docs are really new to me, and I'm just trying a lot of new things out so I can publish this to my team.

Any help would be much appreciated! Thanks!

=============== UPDATE 1.0 =================

So, I added this plugin before the 'asciidoctor' 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>

And yes, I had to include the version because otherwise I would get an error saying it wasn't there, but it was still a successful build. However, now none of my tests will run.

I have also changed my index.adoc to include the following:

[[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[]

And so, because tests aren't running, it is not adding these files. I also suspect that 'response-headers.adoc' isn't being generated either. When the tests were running, I was getting the snippets.

I think I will be on the right track if I can get the tests running again. I am not skipping the tests at all.

=============== UPDATE 2.0 =================

I changed the surefire plugin to actually work with the tests I have:

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

Since all my tests, end in /*Test.java
So, this made all my tests execute.

Since I was getting a message that the *.adoc files were missing, I double checked that

<properties>
    <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>

was setup correct, but I didn't realize this had been removed, so I re-added it, and I stopped getting error messages.

I don't recall if I mentioned it, but I added details to index.adoc and then I was finally able to get a generated index.html with content in it.

I now, just need to learn AsciiDoctor more, and I can update the index.adoc for all the POSTS's and PUT's as well as the GET's.

Upvotes: 0

Views: 826

Answers (1)

tjholmes66
tjholmes66

Reputation: 1998

After experimentation as detailed above, I finally got this to work. I just had to have the configuration correct, and finally it works. I now have index.adoc files created and an index.html file created with content.

I now, just need to learn AsciiDoctor more, and I can update the index.adoc for all the POSTS's and PUT's as well as the GET's.

Upvotes: 0

Related Questions