Usando o WADL para Gerar Documentação de Serviço

O Web Application Description Language (WADL) é uma linguagem de descrição para os aplicativos baseados em HTTP. Atualmente ele é um World Wide Web Consortium (W3C) Member Submission. O WADL pode ser usado por programas para fornecer informações sobre o serviço em um método processável pela máquina. Por exemplo, é possível usar um documento Extensible Stylesheet Transformation (XSLT) para transformar a documentação WADL usando um XSLT customizado e um processador XSLT.

Sobre Esta Tarefa

Por padrão, um documento WADL pode ser solicitado para um determinado recurso ao chamar uma solicitação HTTP OPTIONS para qualquer URL de Java™ API para RESTful Web Services (JAX-RS). É possível emitir uma solicitação OPTIONS com a maioria dos clientes HTTP. O documento WADL retornado a partir da solicitação descreve o recurso usando informações a partir das anotações JAX-RS.

O WADL é um padrão de desenvolvimento que ajuda a descrever os serviços disponíveis para os usuários. Os documentos WADL são gravados XML. Usando os analisadores XSTL ou XML, os desenvolvedores podem gerar documentação para o serviço. Em alguns casos, os usuários podem desenvolver clientes para entender dinamicamente o serviço RESTful ao inspecionar o documento WADL.

Usando o IBM® JAX-RS, os desenvolvedores podem gerar uma representação XML JAXB de um documento WADL, descrevendo todos os recursos disponíveis no aplicativo. A representação JAXB pode ser retornada a partir de um método de recurso JAX-RS. Em seguida, o recurso de documento WADL é tratado como qualquer outro recurso JAX-RS e pode ser usado pelos clientes.

Procedimento

  1. Configure o ambiente de desenvolvimento.
    1. Antes de iniciar o desenvolvimento de aplicativos JAX-RS, é necessário configurar o ambiente de desenvolvimento incluindo as bibliotecas JAX-RS no caminho de classe.
  2. Definir os recursos nos aplicativos da Web JAX-RS.
    1. Os recursos são o bloco de construção básico de um serviço RESTful. Os recursos podem conter dados estáticos ou atualizados dinamicamente. Os exemplos de recursos a partir de um aplicativo de armazenamento de manual online incluem um manual, uma ordem de um armazenamento e uma coleta de usuários. Ao identificar os recursos no seu aplicativo, poderá tornar seu serviço mais útil e fácil de desenvolver.
  3. Configure o aplicativo JAX-RS.

    É possível configurar aplicativos JAX-RS de várias formas dependendo de suas necessidades. Para aproveitar a funcionalidade Java Platform, Enterprise Edition (Java EE) 6, é possível usar os recursos de varredura de anotação. Ao usar a varredura de anotação, é possível omitir uma subclasse JAX-RS javax.ws.rs.core.Application ou ter uma subclasse javax.ws.rs.core.Application minimamente definida. Como alternativa, é possível especificar o servlet ou filtro do IBM JAX-RS se quiser usar a funcionalidade disponível no servlet e filtro do IBM JAX-RS.

    Usando um dos métodos de configuração do JAX-RS Versão 1.1, é possível omitir uma subclasse javax.ws.rs.core.Application em seu aplicativo ou ter uma subclasse javax.ws.rs.core.Application que retorne um conjunto vazio de classes para informar o ambiente de tempo de execução do JAX-RS para localizar e usar todas as classes JAX-RS no aplicativo. É possível que você queira usar este método quando não quiser ter que incluir manualmente cada classe JAX-RS relevante em uma subclasse javax.ws.rs.core.Application conforme desenvolve o aplicativo.

    Ao especificar o servlet e filtro IBM JAX-RS específicos, é possível aproveitar e garantir o comportamento do IBM JAX-RS específico. Por exemplo, usar o filtroIBM JAX-RS pode ser útil no desenvolvimento de um aplicativo da Web com uma combinação de recursos JAX-RS e arquivos JavaServer Pages (JSP) com os mesmos padrões de URL.

    Embora haja um método de configuração de JAX-RS V1.1 que suporte o uso de um arquivo web.xml opcional, se quiser especificar restrições de segurança ou funções, ou, se quiser aproveitar os outros recursos ativados usando um arquivo web.xml, você deverá especificar as informações em um arquivo web.xml.

    Escolha um dos três métodos a seguir para configurar seu aplicativo JAX-RS:

    • Configurar aplicativos JAX-RS usando métodos JAX-RS 1.1

      Use este método se quiser usar os recursos de varredura de anotação ou usar os métodos de configuração do JAX-RS 1.1. É possível usar os recursos de varredura de anotação para promover a portabilidade do aplicativo, para minimizar a quantidade de código de configuração ou para modificar o aplicativo de forma dinâmica sem mudanças no código do aplicativo.

    • Configurar o arquivo web.xml para servlets JAX-RS

      Use este método se quiser especificar os recursos que estão ativados usando os parâmetros de inicialização de servlet para alterar o comportamento e garantir que se obtém o servlet IBM JAX-RS. Ao usar os servlets, é possível definir um caminho de servlet no arquivo web.xml que é anexado à URL de base.

    • Configurar o arquivo web.xml para filtros JAX-RS

      Use este método se quiser usar o filtro quando tiver JSPs, outros servlets e filtros e recursos JAX-RS com uma combinação de padrões URL. É possível configurar o arquivo web.xml para definir filtros que indicam as possíveis URLs nas quais o filtro pode ser chamado.

  4. Usar o WADL para gerar documentação de serviço Também é possível construir seu próprio documento WADL ao usar o org.apache.wink.common.model.wadl.WADLGenerator. O WADLGenerator constrói um modelo de objeto anotado Java Architecture for XML Binding (JAXB) para que ele possa ser retornado facilmente como uma resposta de entidade em um método de recurso @OPTIONS, como a entidade de resposta.
  5. Montar aplicativos da Web JAX-RS.
    1. Após desenvolver os arquivos de classe Java para o seu aplicativo da Web JAX-RS e editar o arquivo web.xml para ativar o servlet JAX-RS, você está pronto para montar o aplicativo. Monte o aplicativo da Web em um pacote web archive (WAR). É possível montar o pacote WAR em um pacote archive corporativo (EAR), se necessário.
  6. Implementar aplicativos da Web JAX-RS.
    1. Após ter montado o seu aplicativo da Web JAX-RS, é necessário implementar o seu pacote web archive (WAR) ou o pacote enterprise archive (EAR) no servidor de aplicativos.

Resultados

Um documento de serviço WADL foi incluído no seu aplicativo para permitir que os clientes recuperem uma representação de seu serviço. Por padrão, também é possível emitir as solicitações OPTIONS para seus recursos para recuperar uma representação WADL do recurso individual. Se escolher fazer isso, poderá desativar a geração automática de um documento WADL para as solicitações OPTIONS.


Ícone que indica o tipo de tópico Tópico de Tarefa



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_wink_wadl
Nome do arquivo: twbs_jaxrs_wink_wadl.html