Utilización de WADL para generar documentación de servicio

WADL (Web Application Description Language) ies un lenguaje de descripción para aplicaciones basadas en HTTP. Actualmente, se trata de un envío de miembro de W3C (World Wide Web Consortium). Los programas pueden utilizar WADL para dar información sobre el servicio en un método procesable por las máquinas. Por ejemplo, puede utilizar un documento XLST (Extensible Stylesheet Transformation) para transformar la documentación WADL utilizando un XSLT personalizado y un procesador XSLT.

Acerca de esta tarea

De forma predeterminada, se puede solicitar un documento WADL para un recurso determinado invocando una solicitud OPTIONS HTTP para cualquier URL de API de Java™ para RESTful Web Services (JAX-RS). Puede emitir una petición OPTIONS con la mayoría de los clientes HTTP. El documento WADL devuelto para la solicitud describe el recurso utilizando la información de las anotaciones JAX-RS.

WADL es un estándar de desarrollo que ayuda a describir los servicios disponibles para los usuarios. Los documentos WADL están escritos en XML. Utilizando analizadores XSTL o XML, los desarrolladores pueden generar documentación para el servicio. En algunos casos, los usuarios pueden desarrollar clientes para comprender dinámicamente el servicio RESTful inspeccionando el documento WADL.

Utilizando IBM® JAX-RS, los desarrolladores pueden generar una representación XML JAXB de un documento WADL que describa todos los recursos disponibles en la aplicación. La representación JAXB puede ser devolvuelta por un método de recursos JAX-RS. A continuación, el recurso de documento WADL se trata como cualquier otro recurso JAX-RS y puede ser utilizado por los clientes.

Procedimiento

  1. Configure el entorno de desarrollo.
    1. Antes de comenzar a desarrollar aplicaciones JAX-RS, debe configurar su entorno de desarrollo añadiendo las bibliotecas JAX-RS en la vía de acceso de clases.
  2. Defina los recursos en aplicaciones web JAX-RS.
    1. Los recursos son el bloque de compilación básico de creación de un servicio RESTful. Los recursos pueden contener datos actualizados de forma estática o dinámica. Ejemplos de recursos de una aplicación de almacén de libros en línea incluyen un libro, un pedido en una tienda y una colección de usuarios. Identificando los recursos en la aplicación, puede hacer que el servicio resulte más útil y más fácil de desarrollar.
  3. Configure la aplicación JAX-RS.

    Puede configurar aplicaciones JAX-RS de varias maneras en función de sus necesidades. Para sacar partido de la funcionalidad de Java Platform, Enterprise Edition (Java EE) 6, puede utilizar las prestaciones de exploración de anotaciones. Mediante la utilización de la exploración de anotación, puede omitir una subclase javax.ws.rs.core.Application de JAX-RS o tener una subclase javax.ws.rs.core.Application mínimamente definida. Como alternativa, puede especificar el servlet o filtro IBM JAX-RS si desea utilizar la funcionalidad disponible en el servlet y filtro IBM JAX-RS.

    Si utiliza uno de los métodos de configuración de JAX-RS Versión 1.1, puede omitir una subclase javax.ws.rs.core.Application en la aplicación o disponer de una subclase javax.ws.rs.core.Application que devuelva un conjunto vacío de clases para informar al entorno de ejecución JAX-RS para que busque y utilice todas las clases JAX-RS de la aplicación. Tal vez desee utilizar este método cuando no quiera añadir manualmente cada clase JAX-RS a una subclase javax.ws.rs.core.Application a medida que desarrolla la aplicación.

    Al especificar el servlet y filtro IBM JAX-RS específicos, puede sacar partido y asegurarse del comportamiento específico de IBM JAX-RS. Por ejemplo, el uso del filtro IBM JAX-RS puede ser útil para el desarrollo de una aplicación web con una mezcla de recursos JAX-RS y archivos JSP (JavaServer Pages) con los mismos patrones de URL.

    Aunque existe un método de configuración de JAX-RS V1.1 que soporta el uso de un archivo web.xml opcional, si desea especificar roles o restricciones de seguridad o desea aprovechar otras características habilitadas utilizando un archivo web.xml, debe especificar la información en un archivo web.xml.

    Elija uno de los tres métodos siguientes para configurar la aplicación JAX-RS:

    • Configurar las aplicaciones JAX-RS con métodos de JAX-RS 1.1

      Utilice este método si desea utilizar las prestaciones de exploración de anotaciones o utilizar los métodos de configuración de JAX-RS 1.1. Puede utilizar las prestaciones de exploración de anotaciones para promover la portabilidad de las aplicaciones, minimizar la cantidad de código de configuración o modificar dinámicamente la aplicación sin cambios en el código de aplicación.

    • Configure el archivo web.xml para los servlets de JAX-RS

      Utilice este método si desea especificar características que se habilitan utilizando parámetros de inicialización de servlet para cambiar el comportamiento y asegurarse de obtener el servlet IBM JAX-RS. Cuando se utilizan servlets, puede definir una vía de acceso del servlet en el archivo web.xml que se añadirá al URL base.

    • Configure el archivo web.xml para los filtros de JAX-RS

      Utilice este método si desea utilizar el filtro cuando tiene los JSP, otros servlets y filtros y recursos JAX-RS con una combinación de patrones de URL. Puede configurar el archivo web.xml para definir filtros que indiquen los URL posibles en los que se puede invocar el filtro.

  4. Utilice WADL para generar documentación de servicio. También puede crear su propio documento WADL utilizando el org.apache.wink.common.model.wadl.WADLGenerator. El WADLGenerator crea un modelo de objeto anotado JAXB (Java Architecture for XML Binding) de forma que pueda devolverlo fácilmente como una respuesta de entidad en un método de recurso @OPTIONS como la respuesta de entidad.
  5. Ensamble las aplicaciones web JAX-RS.
    1. Después de desarrollar los archivos de clase Java para la aplicación web de JAX-RS y tras editar el archivo web.xml para habilitar el servlet de JAX-RS, ya estará listo para ensamblar la aplicación. Ensamble la aplicación web en un paquete WAR (Web Archive). Puede ensamblar el paquete WAR en un paquete archivador empresarial (EAR), si fuera preciso.
  6. Despliegue las aplicaciones web JAX-RS.
    1. Una vez que ha ensamblado la aplicación web JAX-RS, debe desplegar el paquete WAR (Web Archive) o el paquete EAR (Enterprise Archive) en el servidor de aplicaciones.

Resultados

Ha añadido un documento de servicio WADL a la aplicación para permitir a los clientes recuperar una representación del servicio. De forma predeterminada, también puede emitir solicitudes OPTIONS para los recursos para recuperar una representación WADL del recurso individual. Si ha elegido hacerlo, puede inhabilitar la generación automática de un documento WADL para las solicitudes OPTIONS.


Icon that indicates the type of topic Task topic



Timestamp icon Last updated: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_wink_wadl
File name: twbs_jaxrs_wink_wadl.html