By Administrator Updated: Thursday, 11 August 2011 14:48

Documenting WebServices API using Java

Thursday, 11 August 2011 10:55

Generate WebServices API documentation using Java

In the following tutorial we will create a html documentation base on your WebService wsdl file. We will use Maven to manage the dependencies and Xalan to do the transformation of an XSL file to the target Webservice documentation file. The result should look like the following screenshot :

WebServices Documentation sample

Step 1 : Configure the Maven pom of our project

Include the following pom file in your project root in order to include Xalan and JUnit .

Configure Maven to create WebServices documentation


<project xmlns="attp://maven.apache.org/POM/4.0.0" 
    xmlns:xsi="attp://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="attp://maven.apache.org/POM/4.0.0 
    attp://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.ubiteck.sample</groupId>
  <artifactId>xslt</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>XSLT Transformation sample</name>
  <dependencies>
      <dependency>
          <groupId>xalan</groupId>
          <artifactId>xalan</artifactId>
          <version>2.7.1</version>
          <type>jar</type>
          <scope>compile</scope>
      </dependency>
      <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.8.2</version>
          <type>jar</type>
          <scope>test</scope>
      </dependency>
  </dependencies>
</project>

Step 2 : Define the XSL transformation file

Tomi Vanek has wrotten an excellent xslt file . It can be downloaded at http://tomi.vanek.sk/xml/wsdl-viewer.xsl

You will download the file and copy the file into your src/main/resources folder according to the recommended Maven directory layout.

Step 3 : Import your wsdl file into the project

In this step we will download or copy our wsdl file into our project. If you have followed our tutorial �about the WebServices using Java you can retrieve the WDSL using the url

http://localhost:8080/WS/MyService?wsdl

Copy the wsdl in your src/test/resources folder

Step 4 : Create the transformation class

We are now ready to create our transformation class.

Make documentation for your Webservices using XSLT


import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.fail;

import java.io.File;
import java.io.FileOutputStream;
import java.io.InputStream;

import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;

import org.junit.Test;

public class WSDLDocumentationGenerator {

    @Test
    public void generate(){
    try {
        TransformerFactory tFactory = TransformerFactory.newInstance();
        InputStream xsl = this.getClass().getClassLoader().getResourceAsStream("wsdl-viewer.xsl");
        InputStream xml = this.getClass().getClassLoader().getResourceAsStream("wsdl.xml");
        assertNotNull("xsl file missing",xsl);
        assertNotNull("xml file missing",xml);
        StreamSource xslSource = new StreamSource(xsl);
        StreamSource xmlSource = new StreamSource(xml);
        assertNotNull("xslSource file missing",xslSource);
        assertNotNull("xmlSource file missing",xslSource);
        Transformer transformer = tFactory.newTransformer(xslSource);
        transformer.transform(xmlSource,new StreamResult(new FileOutputStream(new File("wsdldoc.html"))));
    } catch (Throwable t) {
        t.printStackTrace();
        fail(t.getMessage());
    }
    }
}

You can run the test using the maven comand :

Maven spring tutorial


mvn test

That's it. you have a new wsdldoc.html document containing the documentation of your WebServices according to the Wsdl file provided

Tips and Tricks

If you want to use directly the url of the wsdl �you can use the following Java code:

Documenting WebServices using the wsdl url


public class WSDLDocumentationGenerator {

    @Test
    public void generate(){
	try {
	    TransformerFactory tFactory = TransformerFactory.newInstance();
	    InputStream xsl = this.getClass().getClassLoader().getResourceAsStream("wsdl-viewer.xsl");
	    URL wsdlUrl = new URL("http://localhost:8080/WS/ArticleService?wsdl");
	    StreamSource xslSource = new StreamSource(xsl);
	    StreamSource xmlSource = new StreamSource(wsdlUrl.openStream());
	    Transformer transformer = tFactory.newTransformer(xslSource);
	    FileOutputStream output = new FileOutputStream("wsdlDocumentation.html");
	    transformer.transform(xmlSource,new StreamResult(output));
	    System.out.println("Generation  done !");
	} catch (Throwable t) {
	    t.printStackTrace();
	    fail(t.getMessage());
	}
    }
}

Tags: maven , project , file , attp , step , xalan , wsdl , transformation