Crear ficheros WSDL con documentación con Java y Axis

Ya hemos visto que Microsoft .NET permite agregar documentación a los servicios web de manera muy sencilla. Sin embargo, la herramienta Java2WSDL que proporciona Axis y que aprendimos a utilizar en otro tutorial no permite generar automáticamente ficheros WSDL con documentación. Por lo tanto, si queremos incluir documentación sobre nuestros servicios web implementados en Java y utilizando Axis, tendremos que buscarnos la vida de otra forma.

En este tutorial vamos a usar una transformación XSLT para agregar documentación a un fichero WSDL de una forma más o menos automática.

XSLT es un lenguaje basado en XML y que está pensado para transformar un documento XML en otro documento XML o en cualquier otro documento estructurado. Con la finalidad de identificar partes concretas de los documentos, XSLT utiliza otro lenguaje llamado XPath para realizar consultas sobre un documento XML.

Partimos para ello del siguiente fichero .xsl:

<?xml version="1.0" ?>
<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns="http://schemas.xmlsoap.org/wsdl/">
  <xsl:strip-space elements="*"/>
  <xsl:output method="xml" encoding="UTF-8" indent="yes" />
  <xsl:template match="wsdl:operation">
    <xsl:copy> 
    <xsl:apply-templates select="@*"/> 
    <xsl:call-template name="documentation" />
    <xsl:apply-templates select="node()"/> 
    </xsl:copy>
  </xsl:template>

  <xsl:template name="documentation">
    <xsl:choose>
      <xsl:when test="@name='NombreDeLaOperacion'">
        <wsdl:documentation>DocumentacionDeLaOperacion</wsdl:documentation>
      </xsl:when>
    </xsl:choose>
  </xsl:template>

  <xsl:template match="@*|node()">
    <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy>
  </xsl:template>
</xsl:stylesheet>

En primer lugar tenemos que modificar el texto «NombreDeLaOperacion» del fichero anterior por el nombre de la operación a la que queramos añadir documentación y «DocumentacionDeLaOperacion» por el texto que queramos añadir a la misma a modo de documentación. Agregaremos un bloque similar para cada operación del servicio web que vayamos a documentar.

A continuación vamos a aplicar la transformación XSLT al fichero WSDL original que habíamos generado mediante Axis. En este ejemplo vamos a utilizar Saxon (en su versión java), que es un software destinado a este cometido.

Ejecutaremos el comando que se indica a continuación. «original.wsdl» es el WSDL original generado con Axis, «fichero.xsl» es el fichero que acabamos de definir indicando las transformaciones para añadir documentación y «originalConDocumentacion.wsdl» es el nombre fichero que se va a generar con la documentación ya incluida.

java -classpath saxon.jar com.icl.saxon.StyleSheet original.wsdl fichero.xsl > originalConDocumentacion.wsdl

Ahora tenemos que hacer que Axis nos devuelva el fichero que acabamos de generar cuando preguntemos por el WSDL del servicio web en lugar del que no tiene documentación. Pare ello hacemos lo siguiente:

  • Copiamos el fichero WSDL con la documentación en la ruta «$CATALINA_HOME/webapps/axis/WEB-INF/classes».
  • A continuación editamos el fichero de configuración «$CATALINA_HOME/webapps/axis/WEB-INF/server-config.wsdd» y añadimos la siguiente línea a la operación que corresponda:
    <wsdlFile>/MyService.wsdl</wsdlFile>

Por último, reiniciamos la aplicación Axis y ya tenemos listo y funcionando nuestro WSDL con documentación.

Nuestra puntuación
Twittear
Compartir
Compartir
Pin