Jersey-获取WADL中的HTTP响应状态

Question

我使用Jersey 1.16公开REST API
我希望在生成的WADL中包含HTTP响应代码
我正在像下面的例子一样记录我的代码
据我所知，WADL规范（XSD文件）支持HTTP响应代码
到目前为止，我无法在生成的WADL中获得HTTP响应代码

• 为了在WADL中包含响应代码，记录/注释方法的正确方式是什么
• 为了让Jersey向WADL添加响应代码，还需要做什么吗

代码示例：

/**
 * Delete a workflow.
 * - 404 If the workflow does not exist.
 * - 202 Accepted with async status
 * - 204 No Content if remove is true (workflow is removed immediately)
 */
@DELETE
public Response deleteWorkflow (...) {
    // code goes here
}

Answer 1

首先，要添加有关响应代码的信息，可以使用一些Javadoc标记，这些标记在生成WADL时由Jersey支持和使用。您可以在这里找到它们：SupportedJavadocTagsForExtendedWADL

存在一些自定义标记；其中，有些与特定的响应代码有关：

@response.representation.200.qname
@response.representation.200.mediaType
@response.representation.200.example
@response.representation.200.doc

其中可以用任何代码替换200。

因此，您可以在方法上使用以下javadoc：

/**
 * A method used to demonstrate the supported custom tags.
 * 
 * @param code a code
 * 
 * @response.representation.200.mediaType application/xml
 * 
 */
@GET
@Path("info")
public Response info(@QueryParam("code") Integer code) {
    return Response.status(Response.Status.OK).build(); 
}

其次（假设您使用的是Maven），您需要配置mavenjavadoc插件来创建一个包含以下信息的XML文件：resource-doc.XML（带有由wadl-resourcedoc-doclet工件提供的ResourceDoclet）。

插件配置（用自己的资源包替换.resource.package）：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <executions>
        <execution>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <phase>compile</phase>
        </execution>
    </executions>
    <configuration>
        <encoding>UTF-8</encoding>
        <verbose>false</verbose>
        <show>public</show>
        <subpackages>your.resource.package</subpackages>
        <doclet>com.sun.jersey.wadl.resourcedoc.ResourceDoclet</doclet>
        <docletPath>${path.separator}${project.build.outputDirectory}</docletPath>
        <docletArtifacts>
            <docletArtifact>
                <groupId>com.sun.jersey.contribs</groupId>
                <artifactId>wadl-resourcedoc-doclet</artifactId>
                <version>1.19</version>
            </docletArtifact>
            <docletArtifact>
                <groupId>com.sun.jersey</groupId>
                <artifactId>jersey-server</artifactId>
                <version>1.19</version>
            </docletArtifact>
            <docletArtifact>
                <groupId>xerces</groupId>
                <artifactId>xercesImpl</artifactId>
                <version>2.6.1</version>
            </docletArtifact>
        </docletArtifacts>
        <!-- the following option is required as a work around for version > 2.5 of the javadoc 
            plugin which will be used by a maven version > 2.0.9 -->
        <useStandardDocletOptions>false</useStandardDocletOptions>
        <additionalparam>-output ${project.build.outputDirectory}/resourcedoc.xml</additionalparam>
    </configuration>
</plugin>

第三，扩展com.sun.jersey.api.wadl.config.WadlGeneratorConfig:

public class CustomWadlGeneratorConfig extends WadlGeneratorConfig {
    @Override
    public List<WadlGeneratorDescription> configure() {
        return generator( WadlGeneratorResourceDocSupport.class ) 
            .prop( "resourceDocStream", "resourcedoc.xml" ) 
        .descriptions();
    }
}

第四也是最后一点，您需要指示Jersey使用CustomWadlGeneratorConfig。要做到这一点，请将其添加到应用程序的web.xml中：

<init-param>
    <param-name>com.sun.jersey.config.property.WadlGeneratorConfig</param-name>
    <param-value>com.example.CustomWadlGeneratorConfig</param-value>
</init-param>

javadoc标记中的信息应该包含在WADL中。

遗憾的是，现有的额外标签不允许为每个响应代码指定特定的<doc>，这意味着相同的文本（来自@return标签）将添加到每个代码：

<ns2:response status="200">
    <ns2:doc>
        <![CDATA[text from @return tag]]>
    </ns2:doc>
    <!- ... -->
</ns2:response>
<ns2:response status="404">
    <ns2:doc>
        <![CDATA[text from @return tag]]>
    </ns2:doc>
    <!- ... -->
</ns2:response>

但对于自定义的com.sun.jersey.wadl.resourcedoc.DocProcessor和com.sun.jersey.server.wadl.WadlGenerator，它应该是可行的，如生成的wadl样本所示。

信息和更多示例：

• https://wikis.oracle.com/display/Jersey/HowToConfigureExtendedWADL
• http://biemond.blogspot.be/2013/08/custom-jersey-wadl-generation.html