list - 为资源列表生成 WADL

Question

我现在正在为以下问题苦苦挣扎几天。我搜索了很多答案，在这里，在 Jersey 邮件列表和一般的网络中，但无法找到这个特定问题的答案。

设置问题域...

我在用
Tomcat 7 中的 Jersey 1.16。

我创建了一个简单的 JAX-RS 资源，如下所示:

@Path("/")
@Produces({ "application/xml", "text/plain" })
public class ExampleResource {

    @GET
    public List<Thing> getThings() {
        List<Thing> list = new ArrayList<>();
        list.add(new Thing("a thing 1", "a thing description 1"));
        list.add(new Thing("a thing 2", "a thing description 2"));

        return list;
    }

}

Thing是一个 JAXB 注释的 POJO，看起来像这样

        @XmlRootElement(name = "thing")
        public class Thing {
            private String name;        
            private String description;
// getters, setters and @XmlElement annotations ommited for brevity

我也配置了 WadlGeneratorJAXBGrammarGenerator.class
当我问 GET http://localhost:8092/rest它就像一个魅力 - 格式很好的 Thing 集合被退回。

自动生成的 WADL http://localhost:8092/rest/application.wadl几乎是完美的，它看起来像这样:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
    <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.16 11/28/2012 02:09 PM" />
    <grammars>
        <include href="application.wadl/xsd0.xsd">
            <doc title="Generated" xml:lang="en" />
        </include>
    </grammars>
    <resources base="http://localhost:8092/rest/">
        <resource path="/">
            <method id="getThings" name="GET">
                <response>
                    <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02"
                        xmlns="" element="thing" mediaType="application/xml" />
                    <representation mediaType="text/plain" />
                </response>
            </method>
        </resource>
    </resources>
</application>

就像我说的，几乎完美，问题就在这里。

<ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02"
                            xmlns="" element="thing" mediaType="application/xml" />

WADL 没有描述 /getThings返回 List<Thing> .
相反，它看起来像是指的是单个元素 thing在 xsd0.xsd .
所以，当我喂它时，例如wadl2java，它生成无类型客户端。
为了得到一个 List<Thing>我必须手动编码它，比如
List<Thing> asXml = root().getAsXml(new GenericType<List<Thing>>(){});
有谁知道是否有可能自动生成 WADL 以某种方式表明此特定资源正在返回 列表特定类型的资源？

而我 不要想要创建额外的“ThingList”JAXB 注释类并在我的 Jersey 资源中返回它。

我几乎就可以生成“完美”的 WADL，这正是我遗漏的(希望如此)小部分......

非常感谢!

Answer 1

我遇到了同样的问题并通过生成我自己的 WADL 解决了它。

为此，您需要将以下文件添加到您的项目中

用于高级 WADL 概述注释的 application-doc.xml

application-grammers.xml 定义您的模式的位置(带有您的事物和事物元素和复杂类型)

resourcedoc.xml ，这是由 maven 插件生成的，它读取您的 jersey 类，其中包含您的响应元素 javadoc 注释。

只需将此 HrWadlGeneratorConfig 类添加到您的项目中，并将其作为初始化参数添加到 jersey servlet

    <init-param>
        <param-name>com.sun.jersey.config.property.WadlGeneratorConfig</param-name>
        <param-value>nl.amis.hr.wadl.HrWadlGeneratorConfig</param-value>
    </init-param> 

类(class)

 package nl.amis.hr.wadl;                                                                                        

 import com.sun.jersey.api.wadl.config.WadlGeneratorConfig;                                                      
 import com.sun.jersey.api.wadl.config.WadlGeneratorDescription;                                                 
 import com.sun.jersey.server.wadl.generators.WadlGeneratorApplicationDoc;                                       
 import com.sun.jersey.server.wadl.generators.WadlGeneratorGrammarsSupport;                                      
 import com.sun.jersey.server.wadl.generators.resourcedoc.WadlGeneratorResourceDocSupport;                       
 import com.sun.research.ws.wadl.Grammars;                                                                       
 import com.sun.research.ws.wadl.Include;                                                                        
 import com.sun.research.ws.wadl.ObjectFactory;                                                                  

 import java.util.List;                                                                                          

 public class HrWadlGeneratorConfig extends WadlGeneratorConfig {                                                

     @Override                                                                                                   
     public List<WadlGeneratorDescription> configure() {                                                         
         ObjectFactory obj = new ObjectFactory()  ;                                                              
         Grammars gram = obj.createGrammars();                                                                   
         Include e = obj.createInclude();                                                                        
         e.setHref("schema.xsd");                                                                                
         gram.getInclude().add(e);                                                                               

         WadlGeneratorConfigDescriptionBuilder builder = generator(WadlGeneratorApplicationDoc.class)            
         .prop( "applicationDocsStream", "application-doc.xml" )                                                 
         .generator( WadlGeneratorGrammarsSupport.class )                                                        
         .prop( "grammarsStream", "application-grammars.xml" )                                                   
         .generator( WadlGeneratorResourceDocSupport.class )                                                     
         .prop( "resourceDocStream", "resourcedoc.xml" );                                                        

         return builder.descriptions();                                                                          

     }                                                                                                           

 }                                                                                                               

这是 Jersey 类的片段，@response.representation.200.qname 指向您自己的 schema.xsd 中的元素

  /**
  * Returns the item if existing. 
  * 
  * @response.representation.200.qname employees
  * @response.representation.200.mediaType application/xml,application/json
  * @response.representation.200.doc This is the representation returned by default
  * @response.representation.200.example {@link EmployeeExample#SAMPLE_ITEM}
  *
  *
  * @return the requested item if this service is available
  */
  @GET
  public List<Employee> getEmployees() {
     return  hrBean.getEmployeesFindAll();
  }

以及生成 WADL 生成器使用的 resourcedoc.xml 的 maven pom。

  <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.4</version>
            </plugin>
        </plugins>
  </pluginManagement>                                                                                                                   

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <executions>
                <execution>
                    <goals>
                        <goal>javadoc</goal>
                    </goals>
                    <phase>compile</phase>
                </execution>
            </executions>
            <configuration>
                <encoding>UTF-8</encoding>
                <verbose>false</verbose>
                <show>public</show>
                <subpackages>nl.amis.hr.restful</subpackages>
                <doclet>com.sun.jersey.wadl.resourcedoc.ResourceDoclet</doclet>
                    <docletPath>${path.separator}${project.build.outputDirectory}</docletPath>
                    <docletArtifacts>
                    <docletArtifact>
                          <groupId>nl.amis.hr</groupId>
                          <artifactId>Model</artifactId>
                          <version>1.0-SNAPSHOT</version>
                    </docletArtifact>
                    <docletArtifact>
                        <groupId>com.sun.jersey.contribs</groupId>
                        <artifactId>wadl-resourcedoc-doclet</artifactId>
                        <version>1.17.1</version>
                    </docletArtifact>
                    <docletArtifact>
                        <groupId>com.sun.jersey</groupId>
                        <artifactId>jersey-server</artifactId>
                        <version>1.17.1</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>

这是github上的完整示例
https://github.com/biemond/JDeveloper12c_12.1.2/tree/master/RestFulOWSM/WebService