una tutorial parte hacer español crear creando consumir java rest documentation automation jersey

java - tutorial - Cómo automatizar la documentación de una API REST(implementación de Jersey)



swagger (7)

Escribí una API REST bastante extensa usando Java Jersey (y JAXB). También he escrito la documentación usando un Wiki, pero ha sido un proceso totalmente manual, que es muy propenso a errores, especialmente cuando tenemos que hacer modificaciones, las personas tienden a olvidarse de actualizar el wiki.

Al mirar a su alrededor, la mayoría de las otras API REST también están creando su documentación manualmente. Pero me pregunto si hay una buena solución para esto.

El tipo de cosas que deben documentarse para cada punto final son:

  • Nombre del Servicio
  • Categoría
  • URI
  • Parámetro
  • Tipos de parámetros
  • Tipos de respuesta
  • Esquema de tipo de respuesta (XSD)
  • Solicitudes de muestra y respuestas
  • Tipo de solicitud (Get / Put / Post / Delete)
  • Descripción
  • Códigos de error que pueden ser devueltos

Y luego, por supuesto, hay algunas cosas generales que son globales, como

  • Seguridad
  • Descripción general de REST
  • Manejo de errores
  • Etc

Estas cosas generales están bien para describir una vez y no necesitan ser automatizadas, pero para los propios métodos de servicio web parece muy conveniente automatizarlo.

He pensado quizás en usar anotaciones y escribir un pequeño programa que genere XML, y luego un XSLT que debería generar la documentación real en HTML. ¿Tiene más sentido usar XDoclet personalizado?

Cualquier ayuda sería muy apreciada, Alan

Aunque no estoy seguro de que se ajuste totalmente a sus necesidades, eche un vistazo a enunciate . Parece un buen generador de documentación para varias arquitecturas de servicios web.

EDITAR Enunciado está disponible bajo el paraguas github

Desafortunadamente, la respuesta de Darrel es técnicamente correcta, pero es hocus-pocus en el mundo real. Se basa en el ideal en el que solo algunos se ponen de acuerdo e, incluso si fue muy cuidadoso al respecto, lo más probable es que, por alguna razón fuera de su control, no pueda conformarse exactamente.

Incluso si pudiera, otros desarrolladores que podrían tener que usar su API pueden no interesarse o conocer los detalles de los patrones RESTful ... Recuerde que el objetivo de crear la API es facilitar que otros la utilicen y una buena documentación es una debe.

Sin embargo, el punto de Achim sobre el WADL es bueno. Debido a que existe, deberíamos poder crear una herramienta básica para generar documentación de la API.

Algunas personas han tomado esta ruta, y se ha desarrollado una hoja de estilos XSL para hacer la transformación: https://wadl.dev.java.net/

Es posible que le interese la capacidad de Jersey de proporcionar la denominada descripción WADL para todos los recursos publicados en formato XML en tiempo de ejecución (generada automáticamente a partir de anotaciones). Esto debería contener ya lo que necesita para la documentación básica. Además, es posible que pueda agregar JavaDoc adicional, aunque eso requiere más configuración.

Mire aquí: https://jersey.java.net/documentation/latest/wadl.html

La respuesta de Darrel es exactamente correcta. El tipo de descripción no se debe dar a los clientes de una API REST porque conducirá al desarrollador del cliente a vincular la implementación del cliente con la implementación actual del servicio. Esto es lo que la restricción hipermedia de REST intenta evitar.

Aún puede desarrollar una API que se describa de esa manera, pero debe tener en cuenta que el sistema resultante no implementará el estilo arquitectónico REST y, por lo tanto, no tendrá las propiedades (especialmente la evolvabilidad) garantizadas por REST.

Su interfaz podría ser una mejor solución que RPC, por ejemplo. Pero ten en cuenta qué es lo que estás construyendo.

Ene

Odio ser el portador de malas noticias, pero si sientes la necesidad de documentar las cosas que enumeró, entonces probablemente no has creado una interfaz REST.

Las interfaces REST se documentan identificando una sola URL raíz y luego describiendo el tipo de medio de la representación que se devuelve desde esa URL y todos los tipos de medios a los que se puede acceder mediante enlaces en esa representación.

¿Qué tipos de medios estás usando?

Además, ponga un enlace a RFC2616 en sus documentos. Eso debería explicarle a cualquier consumidor cómo interactuar con su servicio.

Puede encontrar rest-tool útil. Sigue un enfoque independiente del lenguaje para escribir especificaciones, implementación simulada y pruebas unitarias automatizadas para API RESTful.

Puede usarlo solo para documentar sus API, pero esta especificación se puede usar inmediatamente para garantizar la calidad de la implementación de los servicios reales.

Si sus servicios aún no se han implementado por completo, pero, por ejemplo, deben ser utilizados por una aplicación de interfaz web, rest-tool proporciona burlas instantáneas basadas en la descripción del servicio. la validación de esquema de contenido (esquema JSON) también se puede agregar fácilmente al lado de la documentación, así como también puede ser utilizada por las pruebas unitarias.