Maven: How to test that generated documents in target folder are properly generated?

I've got a Java/Maven project that uses RestDocs to generate documentation of our endpoints.

For the uninitiated of RestDocs, what it does is monitor tests during the build and use information from the tests to generate "snippets" that get used to create API documenation using asciidoc during the mvn package phase.

The problem I'm facing is that if the asciidoc (.adoc) file is referencing a non-existent snippet, the doc gets generated and will say something like:

"Unresolved directive in myDoc.adoc - include::{snippets}/error-example/response-fields.adoc[]"

Since this happens after the tests, I don't know how to test for something like this so that the build can stop and let the developer know that they need to update either the .adoc or the snippet.

Any guidance would be much appreciated.

1 answer

  • answered 2018-10-12 16:46 TonyRedYellow

    Adding this to the configuration of the asciidoctor plugin fails the build when a snippet is not found that the .adoc is expecting:

    <logHandler>
         <outputToConsole>true</outputToConsole>
              <failIf>
                  <containsText>include file not found</containsText>
              </failIf>
    </logHandler>