Me gustaría encontrar una forma de generar una buena documentación API REST a partir de código java (WADL o HTML) - basado en JAXB, anotaciones JAX-RS y comentarios de doclet java (no doclet Por favor).Resteasy - generar documentación REST desde Javadoc y anotaciones
Aquí está mi entorno del proyecto
Probar Enunciate.
Enunciate es un motor para mejorar drásticamente su API de servicios web Java. Es simple. Desarrolla su API de servicio web utilizando tecnologías Java estándar y adjunta Enunciate a su proceso de compilación. De repente, su API de servicios web se jacta de algunas características bastante impresionantes:
- Documentación HTML completa de sus servicios, extraída de su JavaDocs.
- Bibliotecas del lado del cliente (por ejemplo, Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) para desarrolladores que desean interactuar con su API.
- Interface Definition (por ejemplo, los documentos WSDL, WADL, el esquema de XML, etc.)
- Etc.
Las API del compilador de Java le permiten escribir código que analiza el origen de Java y realiza su propio procesamiento.
Aquí hay un instructional article, que incluye información sobre el análisis de anotaciones.
Supongo que puede extraer la información sin procesar que necesita con estas API. Sin embargo, esto arrojará datos sintácticos: las URL REST, las acciones y los parámetros, un usuario también se beneficiaría de una explicación adicional, que el autor del servicio podría (¿debería?) Proporcionar en Java Doc.
la solución completa podría ser analizar tanto la anotación como el documento Java y combinar los dos.
bien ... pero me gustaría tener más como el complemento maven que manejaría esto para mí, y SOLAMENTE generación de doc, no lib cliente o algo así. –
Supongo que estoy asumiendo que un complemento aún no existe, y sugiero cómo se podría escribir. Mi recomendación sería solo usar JavaDoc. – djna
Como alternativa a Enunciate, también se podrían considerar MireDot. Creció a partir de una herramienta que utilizamos dentro de nuestra propia empresa y es de uso gratuito para proyectos de código abierto. Hace exactamente lo que describes: combina las anotaciones de jaxrs y los comentarios de javadoc existentes para generar una API de descanso. Funciona como un plugin maven que solo debes agregar a tu proyecto. Las anotaciones de Jaxb aún no se admiten en el momento de la redacción, pero la herramienta se encuentra en desarrollo activo y elegimos las funciones para implementarlas en base a sugerencias/solicitudes/comentarios.
¡Probé MireDot hace un momento, y es REALMENTE BUENO! – thermz
He usado MireDot con RestEasy y es realmente genial y fácil de configurar –
El único "problema" con MireDot es la clave de licencia requerida. Uno por artefacto ... (incluso para la parte libre) –
No se puede encontrar en la web. ¿Nadie? –
Se puede encontrar en https://github.com/stoicflame/enunciate – vim