Swagger

Documentando APIs

  • admin 

DOCUMENTANDO APIs

Filón de herramientas que generan la documentación automáticamente en la web de las APIs generadas a partir de los ficheros OpenAPI.

Voy poniendo todas las que he encontrado, porque son unas cuantas y el resultado es cuestión de gustos.

La que veo más avanzada en cuestión de actualizaciones y contribuyentes es Redoc:

https://apis.guru/blog/redoc-release/

https://swagger.io/blog/redoc-openapi-powered-documentation/

https://github.com/Rebilly/ReDoc/

Pero no es la única existente, y hay otros proyectos que tampoco tienen mala pinta, como Spectacle:

https://github.com/sourcey/spectacle

O DapperDox (este está hecho en golang ;-)):

http://dapperdox.io/

https://github.com/DapperDox/dapperdox

Por cierto, el propio Swagger tiene su sistema de generación de documentación, pero por lo que se ve en los blogs todo el mundo coincide que el Swagger es más indicado para editar y validar los ficheros OpenAPI (es decir, es una herramienta más orientada para trabajar en la parte de definición de los APIs), que para generar la documentación, al menos no de la forma tan extensa en que lo hacen las herramientas anteriores:

http://idratherbewriting.com/learnapidoc/pubapis_swagger.html

https://github.com/swagger-api/swagger-ui

Por ultimo, os dejo un enlace de un blog donde hace un repaso a bastantes herramientas de documentación de APIs, no solo de OpenAPI. Lo he encontrado después de haber encontrado los proyectos anteriores, pero lo veo bastante completo por si queréis explorar otras herramientas:

https://pronovix.com/blog/free-and-open-source-api-documentation-tools

Por cierto, los de APIs.guru son expertos en la publicación y análisis de APIs (son los creadores de Redoc) en un sistema llamado GraphQL (aparte del OpenAPI) y tienen varios proyectos sorprendentes para sacarle el máximo partido a esta forma de trabajar con modelos de datos:

https://apis.guru/

http://graphql.org/

El GraphQL lo usan para sus aplicaciones móviles la gente de Facebook, por ejemplo. Uno de los proyectos sobre GraphQL que han desarrollado los de APIs.guru es un navegador de GraphQL:

https://github.com/APIs-guru/graphql-voyager

La demo que tienen sobre varios APIs (incluido el de GitHub) es impresionante. Merece la pena echarle un vistazo para darse cuenta del potencial que tiene (p.e. elegid el esquema de GitHub y uno de los nodos raíces):

https://apis.guru/graphql-voyager/