如何使用 Enunciate 为 Spring-Jersey 项目生成 REST 文档？答案

【问题标题】：How to Generate REST Docs with Enunciate for a Spring-Jersey Project?如何使用 Enunciate 为 Spring-Jersey 项目生成 REST 文档？
【发布时间】：2012-06-11 13:17:58
【问题描述】：

我正在努力解决我认为很简单的事情 - 为一组已经存在的 REST 服务生成文档，这些服务基本上只是带有 JAX-RS 注释的 POJO 注释。我使用 Jersey 作为实现提供者。 REST API 被部署为 Spring Web 应用程序的一部分。

我只想为 REST 服务 POJO 生成文档，所以我的 enunciate.xml 配置是这样的：

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

我已按照 enunciate 文档中的建议配置了我的 pom.xml：

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

但是当我运行 mvn enunciate:docs 时，我收到以下构建错误：

[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

我想不通，我做错了什么。有什么想法吗？

【问题讨论】：

标签： spring maven jersey enunciate

【解决方案1】：

如果配置文档目录会出现这种情况吗？

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

编辑：忘记关闭 docsDir

【讨论】：

是的。即使我将绝对路径设置为docs-目录，也会发生同样的错误。您能否建议我可以尝试的更多事情或一些故障排除步骤？我真的很感激。
你不会相信实际的错误是什么。我是在另一个也使用相同 Jersey 依赖项的项目中发现它的。我也有同样的bad LOC-exception。我认为这不是巧合，我是对的。显然，Maven 下载的球衣 jar 已损坏。因此，这不是一个明确的特定错误。移除损坏的 jar 并获得一个新的似乎让我滚动。还是谢谢！

【解决方案2】：

在您的 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>

具有以下属性：

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

在您的 Maven 主页中，确保您有一个名为 enunciate.xml 的 xml 文件，其中包含以下代码行：

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

【讨论】：