RESTful JSON API Documentation Generator

Question

Me pregunto si alguien tiene alguna experiencia o recomendaciones para las herramientas que se pueden utilizar para generar páginas web que documentan y le permiten jugar con una API RESTful JSON. Estoy pensando en algo como Github Developer API o Google API Console.

Mirando a su alrededor, he encontrado swagger de Wordnik, que se ve bien. Pero me pregunto si hay algo más y la experiencia de la gente con estas herramientas. Gracias.

Answer 1

Hay algo más como enunciate y I/O Docs.

Y aquí es un blog sobre este tema: Automated Documentation for REST APIs

Answer 2

Estamos trabajando en un producto llamado http://apiengine.io para resolver este problema

Answer 3

me gusta Apiary. Todavía en flujo, pero luciendo bastante bien.

Answer 4

Acabo de crear una gema de rubí "calamum" que genere un html rest api doc, es fácil de usar. https://github.com/malachheb/calamum.

Answer 5

Swagger podría ser para usted. Tiene implementaciones en varios idiomas.

Answer 6

Estamos trabajando en MireDot que trabaja para Java/JAX-RS. Una configuración inicial toma menos de 5 minutos. Una versión base muy capaz es gratis.

Answer 7

Mi recomendación sería no confiar demasiado en los generadores [del código fuente]. Creo que el público del documento finalmente es humano y necesita mucho más de lo que los archivos generados por WADL y máquina pueden proporcionar. Para ayudar a las herramientas, debes invertir tiempo y esfuerzo para dominar las idosyncracies de una herramienta.

Además, existe un límite práctico real sobre cuánto se puede incluir dentro del código fuente de una API. La mera documentación de nombres y tipos de parámetros no será de mucha ayuda (y completa) y la adición de solicitud de muestra y respuesta dentro del código fuente se ve mal (aunque es información esencial para los usuarios finales). Otra razón puede ser simplemente estética.

Twitter también mantiene los documentos a mano y eso es mucho decir. En mi humilde opinión, la mejor opción sería mantener la documentación en un formato amigable para los humanos y generar HTML/PDF, etc. a partir de eso.

Shameless Plug

https://github.com/rjha/restdoc

Esto es sólo par de scripts PHP muy simples que leen API de archivos de definición de YAML y generan HTML. Puede que no se adapte bien a la enorme API de EBay, pero para los simples requisitos de documentación de la API, este puede ser un camino por recorrer.

Answer 8

rest-tool es sencilla herramienta de línea de comandos escrito en JavaScript utilizando Node.js. Hace posible crear proyectos independientes que proporcionan documentación, emulación y pruebas automáticas de API RESTful.

puede crear unas API que trabajan en un par de minutos que actúa como una zona desmilitarizada entre el cliente y del servidor desarrolladores.

Genera la documentación, los casos de prueba e incluso la lógica simulada dinámica del lado del servidor basada en plantillas, por lo que todo es altamente personalizable.

Answer 9

Acabo de crear Swadl, un generador de documentación WADL inspirado en la moda.

Básicamente, no hay integración en absoluto, solo pásalo y crea la página.

Échale un vistazo aquí: https://github.com/ehearty/Swadl

Y ver una demostración aquí: http://ehearty.github.io/Swadl/wadl.html

Me encantaría retroalimentación sobre mi herramienta

Answer 10

la cuestión es bastante antiguo, pero creo que sigue siendo real. Soy consciente de tres API herramientas de diseño:

• Swagger (no hay una solución SaaS)
• RAML (apihub.com)
• API Blueprint (apiary.com) Todas ellas están cubiertas de esta entrada del blog - http://apievangelist.com/2014/03/08/hello-world-product-api-with-blueprint-raml-and-swagger/
  le recomiendo seguir ese tipo si usted está interesado en las API

personalmente, creo que esas herramientas son buenas para el intercambio de documentos de la API entre los miembros de equipos relativamente pequeños de desarrolladores donde cada desarrollador conoce la mayoría de los detalles específicos para un proyecto en particular y, literalmente, solo necesita saber si es POST o PUT y cuáles son los nombres de los campos JSON resultantes.

Necesitábamos tener características ricas y prácticas de gestión de contenido junto con la materia específica RESTO lo que produciría bellos documentos en varios formatos como de una sola página html o pdf No pudimos encontrar el software decente, así que hemos decidido crear Speca.io

Por el momento está en alfa y es totalmente gratuito, pero estamos encantados de jugarlo y cualquier comentario será apreciado.