How to Generate REST Docs with Enunciate for a Spring-Jersey Project?

I'm struggling with something that I thought is quite simple - to generate documentation for a set of already existing REST services, which are basically just POJOs annotates with JAX-RS annotations. I'm using Jersey as an implementation provider. The REST API is deployed as part of a Spring web application.

I want to generate only the documentation for the REST services POJOs, so my enunciate.xml configuration is something like that:

<?xml version="1.0"?>
<enunciate label="novaglobalapi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://enunciate.codehaus.org/schemas/enunciate-1.25.xsd">

    <api-classes>
        <include pattern="com.something.api.rest.*"/>
    </api-classes>

    <modules>
        <docs docsDir="restapi" title="REST API"/>
    </modules>
</enunciate>

I've configured my pom.xml as suggested in the enunciate documentation:

<build>
...
    <plugin>
        <groupId>org.codehaus.enunciate</groupId>
            <artifactId>maven-enunciate-plugin</artifactId>
            <version>1.25</version>
            <executions>
                <execution>
                    <goals>
                        <goal>docs</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <configFile>enunciate.xml</configFile>
            </configuration>
    </plugin>
...
</build>

But when I run mvn enunciate:docs, I'm getting the following build error:

[ERROR] Failed to execute goal org.codehaus.enunciate:maven-enunciate-plugin:1.25:docs (default-cli) on project NovaGlobalSSOAPI: Problem assembling the enunciate app. invalid LOC header (bad signature) -> [Help 1]
org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal org.codehaus.enunciate:maven-enunciate-plugin:1.25:docs (default-cli) on project NovaGlobalSSOAPI: Problem assembling the enunciate app.
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:217)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:84)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:59)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.singleThreadedBuild(LifecycleStarter.java:183)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:161)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:319)
    at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:156)
    at org.apache.maven.cli.MavenCli.execute(MavenCli.java:537)
    at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:196)
    at org.apache.maven.cli.MavenCli.main(MavenCli.java:141)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke(Method.java:597)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:290)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:230)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:409)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:352)
Caused by: org.apache.maven.plugin.MojoExecutionException: Problem assembling the enunciate app.
    at org.codehaus.enunciate.DocsMojo.execute(DocsMojo.java:99)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:101)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:209)
    ... 19 more
Caused by: java.util.zip.ZipException: invalid LOC header (bad signature)
    at java.util.zip.ZipFile.read(Native Method)
    at java.util.zip.ZipFile.access$1200(ZipFile.java:31)
    at java.util.zip.ZipFile$ZipFileInputStream.read(ZipFile.java:459)
    at java.util.zip.ZipFile$1.fill(ZipFile.java:242)
    at java.util.zip.InflaterInputStream.read(InflaterInputStream.java:141)
    at java.io.DataInputStream.readFully(DataInputStream.java:178)
    at java.util.jar.JarFile.getBytes(JarFile.java:362)
    at java.util.jar.JarFile.getManifestFromReference(JarFile.java:161)
    at java.util.jar.JarFile.getManifest(JarFile.java:148)
    at org.codehaus.enunciate.main.Enunciate.scanClasspath(Enunciate.java:409)
    at org.codehaus.enunciate.main.Enunciate.doGenerate(Enunciate.java:319)
    at org.codehaus.enunciate.ConfigMojo$MavenSpecificEnunciate.doGenerate(ConfigMojo.java:634)
    at org.codehaus.enunciate.main.Enunciate$Stepper.step(Enunciate.java:1706)
    at org.codehaus.enunciate.main.Enunciate$Stepper.stepTo(Enunciate.java:1738)
    at org.codehaus.enunciate.DocsMojo.execute(DocsMojo.java:95)
    ... 21 more

I can not figure out, what am I doing wrong. Any ideas?

Answers


Does it happen if you configure the documentation directory?

<build>
...
    <plugin>
        <groupId>org.codehaus.enunciate</groupId>
        <artifactId>maven-enunciate-plugin</artifactId>
        <version>1.25</version>
        <executions>
            <execution>
                <goals>
                    <goal>docs</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <!-- the directory where to put the docs -->
            <docsDir>${project.build.directory}/docs</docsDir>
            <configFile>enunciate.xml</configFile>
        </configuration>
    </plugin>
...
</build>

Edit: forgot to close docsDir


Use the following code in your maven pom:

    <build>
        <plugins>
            <plugin>
                <groupId>com.webcohesion.enunciate</groupId>
                <artifactId>enunciate-maven-plugin</artifactId>
                <version>${enunciate.version}</version>
                <configuration>
                  <sourcepath-includes>
                    <sourcepath-include>
                      <groupId>com.your.company.web.rest</groupId>
                    </sourcepath-include>
                    <sourcepath-include>
                      <groupId>com.external</groupId>
                      <artifactId>external</artifactId>
                    </sourcepath-include>
                  </sourcepath-includes>
                </configuration>
                <executions>
                  <execution>
                    <goals>
                      <goal>assemble</goal>
                    </goals>
                  </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

With the following property:

<properties><enunciate.version>2.10.1</enunciate.version></properties>

In your maven home make sure you have an xml file called enunciate.xml with the following lines of code:

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.0.0-M.4.xsd">

  <title>Your Company REST API</title>
  <description package="com.your.company.web.api"/>
  <copyright>www.yourcompany.com</copyright>

    <api-classes>
        <include pattern="com.your.company.web.rest.*"/>
    </api-classes>

    <modules>
        <docs docsDir="src/main/webapp/restapi" title="Your Company REST API"/>
        <jackson disabled="true"/>
        <swagger basePath="/yourcompany/api/"/>
    </modules>

</enunciate>

Need Your Help

Mutex vs busy wait for tcp io

c linux multithreading tcp mutex

I do not care about being a cpu hog as I have one thread assigned to each core and the system threads blocked off to their own set. My understanding is that mutex is of use when other tasks are to ...

What would be too big for a dictionary, when using IEnumerable.ToDictionary()?

c# performance design-patterns dictionary ienumerable

Say that, in my method, I pass in a couple IEnumerables (probably because I'm going to get a bunch of objects from a db or something).