Ovlivnění generovaného WADL

Při buildování REST aplikací, s využitím implementace Jersey, se automaticky generuje i WADL. Tento je možné částečně doplňovat. Nyní ukáži postup přidávání dokumentačních elementů do generovaného WADL.

1) Vytvořím soubor application-doc.xml, tento soubor obsahuje stručný popis aplikace. Příklad:

 <applicationDocs targetNamespace="http://wadl.dev.java.net/2009/02">  
     <doc title="Post Code" xml:lang="en">Title and high level description</doc>  
 </applicationDocs>

2) Vytvořím soubor application-grammars.xml obsahující umístění vlastních XML schemat. Příklad:

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
 <grammars xmlns="http://wadl.dev.java.net/2009/02"   xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xi="http://www.w3.org/1999/XML/xinclude">  
   <include href="../xsd/schema.xsd" />  
 </grammars>  

3) Vytvořím potomka třídy WadlGeneratorConfig, v kterém budou uvedeny oba XML soubory vytvořené v předchozích krocích. Navíc je přidán soubor resourcedoc.xml, který bude vygenerován.

 package biz.prodejna.rest  
 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 java.util.List;  
 public class MyWadlGeneratorConfig extends WadlGeneratorConfig {  
   @Override  
   public List<WadlGeneratorDescription> configure() {  
     return generator( WadlGeneratorApplicationDoc.class )  
      .prop( "applicationDocsStream", "application-doc.xml" )  
      .generator( WadlGeneratorGrammarsSupport.class )  
      .prop( "grammarsStream", "application-grammars.xml" )  
      .generator( WadlGeneratorResourceDocSupport.class )  
      .prop( "resourceDocStream", "resourcedoc.xml" )  
      .descriptions();  
   }  
 }  

4) Třídu vytvořenou v předchozím kroku uvedu jako inicializační parametr JerseyServletu ve web.xml

 <servlet>  
     <servlet-name>JerseyServlet</servlet-name>  
     <servlet-class>  
       com.sun.jersey.spi.container.servlet.ServletContainer  
     </servlet-class>  
     <init-param>  
       <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>  
       <param-value>true</param-value>  
     </init-param>  
     <init-param>  
       <param-name>com.sun.jersey.config.property.WadlGeneratorConfig</param-name>  
       <param-value>biz.prodejna.rest.MyWadlGeneratorConfig</param-value>  
     </init-param>  
     <load-on-startup>1</load-on-startup>  
 </servlet>  

5) Aby byl vygenerován soubor resourcedoc.xml je třeba do pom.xml přidat maven javadoc plugin s docletem com.sun.jersey.wadl.resourcedoc.ResourceDoclet.

 <plugin>  
    <groupId>org.apache.maven.plugins</groupId>  
    <artifactId>maven-javadoc-plugin</artifactId>  
    <version>2.9.1</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>biz.prodejna.rest</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>${jersey-release-version}</version>  
        </docletArtifact>  
        <docletArtifact>  
            <groupId>com.sun.jersey</groupId>  
            <artifactId>jersey-server</artifactId>  
            <version>${jersey-release-version}</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>  

6) Aby se generovaly doc elementy i k jednotlivým parametrům je do pom.xml třeba přidat závislost

 <dependency>  
   <groupId>javax.ws.rs</groupId>  
   <artifactId>javax.ws.rs-api</artifactId>  
   <version>2.0</version>  
 </dependency>  

Nyní by celé řešení mělo být funkční. Pokud přijdete na to jak v elementech parametrů generovat atribut required můžete mi o tom dát vědět do diskuze níže. Nebo máte jiný způsob jak co nepřesněji definovat REST API? I o tom se rád dočtu.