Question

我使用Jersey 1.16来暴露REST API 我想在生成的WADL中使用HTTP响应代码我正在记录我的代码，如下例所示据我所知WADL规范（XSD文件）supports the HTTP response codes。
至于现在，我无法在生成的WADL中获得HTTP响应代码。

为了在WADL中获得响应代码，记录/注释方法的正确方法是什么？
为了让泽西岛将响应代码添加到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

首先，要添加有关响应代码的信息，您可以使用Jersey生成WADL时支持和使用的一些Javadoc标记。您可以在此处找到它们：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），您需要配置maven-javadoc-plugin以创建包含以下信息的XML文件：resource-doc.xml（使用wadl-resourcedoc-doclet提供的ResourceDoclet）伪影）。

插件配置（将your.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应该可行，如generate-wadl samples所示。

信息和更多示例：

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

1 个答案: