¿Qué herramienta usaría para producir documentos de API REST a partir de código Java?

Hay muchas de estas herramientas para elegir, de diferentes niveles de calidad y varios modelos, desde código abierto hasta comercial.

Necesito documentar API REST, ya sea Spring MVC o javax.ws.rs.

Mis prioridades son:

  1. Produzca algo de documentación HTML a partir del código anotado de javax.ws.rs.

  2. Javadoc ya escrito para la API y los parámetros y excepciones deben incorporarse a los documentos generados.

  3. Se prefiere una documentación atractiva que sea fácil de entender en el contexto de lo que está viendo y navegar. No tenemos tiempo para personalizar la apariencia, lo que sea que saque de la caja tiene que servir.

Y algunos extras opcionales:

  1. Permitir que se agregue contenido extra a la documentación generada, como ejemplos. Cuando se vuelve a generar la documentación, esta documentación definida por el usuario debe sobrevivir y permanecer adjunta a la misma documentación de puntos finales para la que se escribió.

  2. Un editor interactivo para lo anterior.

  3. Genere swagger, raml, hal u otros formatos de metadatos y conéctelos al servicio en ejecución. Esto se utilizará principalmente para permitir a los usuarios navegar por la API de un servicio en ejecución y, posiblemente, también para enviar casos de prueba manualmente.

¿Qué herramientas crees que son las mejores?

¿Por qué no usaría simplemente Javadoc?
Documentar la API REST, no la API de Java. Los dos se asignan junto con anotaciones (el bit javax.ws.rs). Quiero tomar lo que pueda formar el javadoc y producir una buena documentación de API REST a partir de eso.
¿Alguna recomendación más?
Estoy pensando en algo que use swagger, pero aún no encontré la herramienta adecuada que haga buenos documentos para humanos con ejemplos, etc. y swagger también.

Respuestas (2)

MireDot está diseñado para esto.

  • Entrada: Jax-rs, Spring Web-mvc, código Jackson/archivos de configuración
  • Salida: HTML y RAML entre otras opciones

Los requisitos 1/2/3 se cumplen pero los requisitos opcionales 4/5/6 solo en parte, en particular, la salida es de solo lectura.

Ejemplo de salida HTML: http://miredot.com/exampledocs/

Es gratuito para proyectos de código abierto .

Nota: no lo he probado yo mismo.

Fundador de Miredot aquí. De hecho, los requisitos 4/5 solo están parcialmente cubiertos. Puede agregar un párrafo introductorio en html y, para agregar ejemplos, puede, por supuesto, usar el diseño html dentro de Javadoc. Para el requisito 6, tenemos salida RAML. Swagger probablemente seguirá en los próximos meses.
@bertvh: ¡Gracias! Avíseme cuando Swagger y otras funciones solicitadas por el autor de la pregunta estén disponibles, actualizaré la respuesta.

Yo miraría muy de cerca:

doxígeno

  1. Puede generar HTML, LaTex, RTF (MS-Word), PostScript, PDF con hipervínculos, HTML comprimido y páginas man de Unix.

  2. Es compatible con la documentación de estilo Javadoc .

  3. Es un producto poderoso y maduro que es capaz de producir una buena documentación lista para usar. Sin embargo, tiene una curva de aprendizaje que deberá escalar dependiendo exactamente de lo que desee.

Una respuesta sorprendente. ¿Doxygen hace la documentación de la API REST?
Eric, ¿podría incluir un enlace a la documentación de Doxygen que explique cómo generar documentación para las API REST de Spring MVC o javax.ws.rs? ¡Gracias!
Sería útil si pudiera actualizar su pregunta con (1) ejemplo (s) de cómo su código está documentado o podría estar documentado y (2) exactamente cómo desea que se vea la documentación generada.
¿Qué herramienta usaría para producir documentos de API REST a partir de código Java?
RespuestasAquíPolítica de privacidad1y, 0v