Skip to end of metadata
Go to start of metadata

Just the docs, please.

By default, Enunciate compiles, packages and otherwise integrates itself with your Web service application. The reason for this is to make life easier for the basic developer who doesn't want to have to care about deployment descriptors and configuration.

But there are often cases where you're already compiling and packaging up your own endpoints, and you'd just like to have Enunciate generate it's documentation and client-side libraries. No problem.

Maven

As of Enunciate 1.10, you can use "docs" goal of the the Enunciate Maven Plugin. For example, the following POM snippet will generate all documentation (including client-side libraries) and put them in the "target/docs" directory.

pom.xml

Maven "Site" Inclusion

As of Enunciate 1.17, you can also use the Maven plugin to include the generated documentation as part of the generated Maven site:

pom.xml

Non-Maven Users

The simple answer is that you export the "docs" artifact to a specified (existing) directory or to a file. (If you export it to a file, it will be exported as the zipped-up directory.)

Ant

If you using Ant, this exports the "docs" artifact to the target/docs directory.

build.xml
  • No labels

6 Comments

  1. FWIW, the <docsSubdir> parameter mentioned above doesn't actually seem to work in version 1.17. If you try to use it:

    Embedded error: Error rendering Maven report: Unable to generate web service documentation report
    Unable to export non-existing file C:\Users\MB011000\workspace\system-configuration-rest-server\target\enunciate\build\docs\enunciate

  2. In the ant sample above it should better say

    build.xml

    Alternatively, if the "target/docs" directory exists, Enunciate will automatically unzip the artifact for you.

  3. if you declare the "docs" goal enunciate still tries to compile the sources. I get a compilation exception, because the compiler seems to be unable to handle some generics properly. My guess is that enunciate is trying to use compiled classes that have had erasures alrerady applied, which leads to compiler errors. The project compiles fine with "mvn compile". 

    The error clearly states, that compilation takes place:

    [INFO] invoking enunciate:compile step...

    which results in: ...

    org.codehaus.enunciate.main.Enunciate.invokeJavac(Enunciate.java:874

    Is there a way to explicitly disable the compilation step? So I can use enunciate for documentation-only during normal "mvn clean install" cycles?

  4. I've tried to use the "docs" goal in the wannabecool sample (in place of assemble).  When I do that and issue "mvn install" I get the following error:

    [INFO] Error assembling WAR: webxml attribute is required (or pre-existing WEB-INF/web.xml if executing in update mode)

    NOTE: I'm a mvn beginner so I may be missing something obvious.

  5. Hi,

    Please review the first pom.xml:

                  <!-- the directory where to put the docs -->
                  <docsDir>${project.build.directory}/docs<docsDir>
    Should read:
                  <!-- the directory where to put the docs -->
                  <docsDir>${project.build.directory}/docs</docsDir>
    Thanks!
  6. Client code generation is a cool feature, but I'm primarily interested in the documentation capabilities.  I'm working with an existing codebase implementing a number of services using both JAX-WS and JAX-RS.  The enunciate maven task, using the docs goal described here, fails to generate docs on my project.  This is working, deployed code.  Can someone change the enunciate code to make errors like "The Java client module requires an implementation for each endpoint interface" a warning instead, skipping code generation?  Or, as was asked earlier by Stephan, simply provide a maven goal that actually does what it says and just generates docs without generated code that I don't need?