Herramientas de documentación para las API de RPC

Question

Hay una variedad de buenas herramientas para el código fuente y la documentación de API (Doxygen, Headerdoc, Sphinx, por nombrar algunos). Sin embargo, ninguno de ellos parece especialmente bueno en la producción de documentación para las API que se proporcionan a través de una interfaz RPC (si tiene recomendaciones sobre cómo sintetizar la documentación de la API RPC con estas herramientas, sugiérelo).

estoy especialmente interesado en herramientas de documentación que tienen al menos algún apoyo para JSON y AMQP, pero la pregunta también podría presentarse a las cosas como Protobuf, Thrift, y XML-RPC y cualquier sugerencia de herramientas que trabajan con esas tecnologías haría en menos dame un lugar para comenzar.

Honestamente todavía tengo que ver la documentación de calidad para cualquier interfaz RPC (ya sea a mano o mediante una herramienta), y solo espero que sea porque los desarrolladores son flojos y no porque las herramientas no existan.

Answer 1

Eche un vistazo a Swagger (http://swagger.wordnik.com) - esto es lo que usamos para todas nuestras apis en 3scale (http://www.3scale.net). Básicamente tomará una especificación JSON y hará varias cosas incluyendo crear documentos API interactivos para usted. Los documentos de estilo RPC deberían estar bien (lo enmendamos para recibir/recibir XML). También hay herramientas para generar las especificaciones del código para varios idiomas.

Por último, hay una herramienta de extracción de código simple que puede crear el JSON: https://github.com/solso/source2swagger. Todo esto está menos formalizado que Doxygen, etc., pero podría ser útil para verificarlo.