Header Ads Widget

Ticker

6/recent/ticker-posts

Generadores, exploradores y herramientas de documentación GraphQL



Generar documentación automáticamente  es un sueño hecho realidad para los desarrolladores que buscan centrarse en el código en lugar de en la redacción. También es un sueño para los usuarios finales, que obtienen documentación actualizada y confiable.

GraphQL es un lenguaje de consulta popular que permite a los desarrolladores extraer la información que necesitan de las API. Teniendo en cuenta que hay más de 21.000 API públicas enumeradas en ProgrammableWeb, es muy probable que la necesidad de las capacidades de consulta de GraphQL se vuelva más extrema.

Con la popularidad de GraphQL en aumento, la necesidad de generadores de documentación GraphQL también se volverá más urgente. Hemos compilado algunos de los mejores generadores y herramientas de documentación GraphQL , para ahorrarle valiosas horas al documentar su código.

Generadores, exploradores y herramientas de documentación GraphQL: un resumen

Los generadores de documentación le permiten concentrarse en escribir un código excelente y atender las necesidades de sus clientes y compañeros programadores. También garantizan que su documentación esté siempre actualizada, ya que se genera desde la propia API.

Los exploradores de documentación son igualmente importantes. Los desarrolladores pueden perderse buscando una consulta o tipo de archivo en particular, perdiendo el impulso y escribiendo código torpe. Los exploradores de documentación GraphQL permiten a los desarrolladores comprender la sintaxis y examinar la documentación de una manera útil.

Finalmente, también hemos compilado algunas herramientas GraphQL útiles que beneficiarán su desarrollo de API. Le ayudarán a aprovechar al máximo la potente capacidad de consulta dirigida de GraphQL.

Generadores de documentación GraphQL

Documentos GraphQL

¿Busca un generador de documentación estática limpio y fácil de usar? GraphQL Docs de Scaphold.io produce documentación minimalista y comprensible. Supuestamente se genera en menos de 10 segundos, simplemente ingresando una URL de punto final GraphQL. Una vez que haya generado su documentación estática, podrá hacerla pública o mantenerla privada.

GraphQL Doc de Scaphold.io genera rápidamente documentos GraphQL simples.

Graphdoc

Graphdoc es un equivalente de código abierto de GraphQL Docs. Al igual que GraphQL Docs, Graphcdoc también crea páginas de documentación estáticas utilizando solo una URL de punto final. Graphdoc se puede integrar fácilmente en varios entornos de desarrollo diferentes, desde Rails hasta Ruby y JSON.

Graphdoc es un generador de páginas estáticas de código abierto para documentar el esquema GraphQL.

DocQL (Beta)

Actualmente en una versión beta cerrada al momento de escribir este artículo, DocQL genera documentación directamente desde un esquema GraphQL. Las páginas de documentación se crean automáticamente como subdominios del dominio 'hubs.docql.io', pero los dominios personalizados son posibles. La documentación se puede personalizar a través de un conjunto de temas CSS personalizados y seleccionados. Las funciones futuras de DocQL pendientes incluyen actualizaciones automáticas, guías de usuario personalizadas en un "Centro de API".

La capacidad de DocQL para crear  guías de usuario es una característica prometedora. Puede cargar un repositorio de Git como fuente para su guía de API personalizada, que se genera mediante un archivo de configuración simple basado en YAML.

¿El único inconveniente? DocQL cuesta dinero. Actualmente tiene un precio de $ 80 / mes, como mínimo. Si solo está experimentando con las herramientas de documentación GraphQL, es posible que lo haga mejor experimentando primero con las opciones de código abierto.

Cuando se lance por completo, DocQL generará documentos y guías de usuario en un "Centro de API".

Graphqldoc por Mvochoa

Si está buscando una herramienta simple y reducida para traducir un esquema GraphQL a un lenguaje de rebajas, este Generador de rebajas de Mvochoa , una variación de Graphqldoc, podría ser justo lo que está buscando.

Exploradores de documentación GraphQL

GraphiQL

GraphiQL (pronunciado Graphical) es un entorno de desarrollo integrado (IDE) en el navegador para explorar GraphQL. Esto hace que la interacción con GraphQL sea mucho más ágil y fácil de navegar. También facilita la programación en GraphQL gracias a una GUI detallada.

GraphiQL presenta una ventana que muestra todas las posibles consultas, campos, mutaciones, tipos y si son necesarios. GraphiQL también permanece sincronizado con GraphQL, eliminando cualquier campo y tipo depreciado de la documentación. No tendrá que preocuparse por escribir código obsoleto, por lo que todo su script funcionará.

GraphiQL IDE mostrado aquí analizando el esquema GraphQL de la API de Star Wars

GraphiQL también admite la depuración sobre la marcha , ofreciendo sugerencias y señalando errores, haciendo que su proceso de codificación sea lo más fluido y fluido posible. También viene equipado con un visor JSON, con todas las características que esperarías de esa función. GraphiQL incluye plegado de código, sangría automática, soporte de copia y solo lectura para que no tenga que preocuparse por eliminar algo accidentalmente.

Finalmente, GraphiQL facilita compartir su trabajo. La URL se actualiza automáticamente cuando se edita una consulta, con toda la sintaxis intacta. Esto hace que sea instantáneo compartir el trabajo con sus colegas u obtener comentarios sobre su trabajo.

GraphiQL es también el explorador de documentación sobre el que se construyen muchos otros entornos GraphQL . Si va a utilizar GraphQL en una capacidad seria, haría bien en familiarizarse con este IDE.

Pros

  • Finalización automática de consultas
  • Resaltado de sintaxis
  • Depurar mientras escribe
  • Explorador de documentación
  • Visor JSON
  • El trabajo se puede compartir fácilmente

Zona de juegos GraphQL

GraphQL Playground es otro IDE en el navegador que se basa en GraphiQL. En realidad, está construido alrededor de GraphiQL. Esto significa que funciona de manera similar pero ofrece características adicionales . Estas funciones están diseñadas para hacer que el flujo de trabajo del desarrollador sea fluido y fluido.

Una de las características más queridas de GraphiQL es el explorador de documentación integrado . Sin embargo, solo ofrece una columna para su explorador, lo que puede dificultar la exploración de tipos profundamente anidados. GraphQL Playground, por otro lado, ofrece múltiples columnas de explorador, así como navegación basada en teclado.

Cuando varios desarrolladores están trabajando con la misma API, a veces los comandos pueden fallar. GraphQL Playground presenta una recarga automática del esquema, lo que significa que el esquema se actualiza cada vez que cambia la API.

Explorando los datos del planeta Star Wars utilizando las increíbles funciones de documentación incorporadas de GraphQL Playground.

Finalmente, GraphQL Playground es una herramienta maravillosa para proyectos colaborativos de GraphQL. Los archivos se pueden compartir directamente con GraphQL Bin , que funciona como Pastebin para consultas GraphQL. También se puede incrustar en su servidor GraphQL, ya sea como un componente de React o como middleware entre marcos como Hapi, Koa o Express.

GraphQL Playground está disponible como una aplicación independiente que se puede ejecutar localmente en su máquina.

Pros:

  • Explorador de esquemas de varias columnas
  • Encabezados personalizados
  • Esquemas de color
  • Pestañas
  • Historial de consultas mejorado
  • Soporte de suscripción GraphQL
  • Se puede compartir fácilmente para colaboraciones
  • Navegación por teclado

Contras:

  • No hay una forma fácil de cerrar columnas de esquema

GraphQL Voyager

Las API pueden volverse increíblemente densas, lo que dificulta la visualización de sus datos y flujo de trabajo. GraphQL Voyager transforma su API GraphQL en un gráfico relacional, que visualiza las conexiones de sus datos una vez que establece su esquema raíz. También es interactivo, lo que le permite resaltar los campos de diferentes tipos de datos cuando se seleccionan y vincularlos a los datos relevantes en el gráfico. GraphQL Voyager también presenta una columna a la izquierda para describir la información del campo y una interfaz visual para una fácil navegación.

Pros:

  • Visualiza datos complejos
  • Hace que los datos se puedan ordenar
  • Fácil de navegar

GraphQL Voyager visualiza las relaciones de sus datos, lo que le permite saber cómo se están desempeñando sus datos de una manera comprensible.

Herramientas GraphQL

Insomnio

Insominia es una poderosa herramienta de prueba de punto final API basada en REST El lema de Insomnia es "depurar como un humano, no como un robot", dejando sus intenciones bastante claras desde el principio. Es un entorno rico en funciones para probar su API GraphQL de varias formas.

Insomnia le permite crear solicitudes HTTP, donde puede especificar la URL, los encabezados y la autorización en una consulta. Insomnia entrega detalles para cada respuesta, devolviendo un código de estado, cuerpo, encabezados y cookies.

La principal ventaja de Insomnia es la capacidad de organizar sus archivos y proyectos. Puede crear espacios de trabajo, carpetas anidadas, solicitudes de arrastrar y soltar e importar y exportar datos fácilmente.

Pruebas GraphQL con Insomnia

Insomnia es un entorno gratuito y de código abierto para Windows, Mac y Linux, lo que significa que casi cualquier persona puede aprovechar la optimización de su flujo de trabajo. Esto también significa que hay una comunidad vibrante de desarrolladores que usan Insomnia. Esto hace que la capacidad de Insomnia para crear complementos para la comunidad de Insomnia sea una ventaja.

Insomnia genera fragmentos de código para más de 12 idiomas diferentes. También cuenta con un área de documentación completa donde puede agregar instrucciones especiales, fragmentos de código y datos de prueba a ciertas llamadas o conexiones.

Finalmente, Insomnia te permite ver respuestas más allá de XML y JSON. Puede ver páginas HTML, PDF, imágenes, SVG y archivos de audio.

El poder de la generación automática con GraphQL

La escritura automatizada ha sido un santo grial de la automatización, la inteligencia artificial y el aprendizaje automático durante algún tiempo. Algunos ya han tenido cierto éxito. Automated Insights , por ejemplo, ha estado utilizando su algoritmo Wordsmith para traducir datos en texto legible. Producen más de mil millones de artículos al año.

La escritura técnica es su propia disciplina única. La capacidad de redactar un copywriting limpio y claro es completamente diferente al conjunto de habilidades necesarias para escribir código eficiente y optimizado. Por lo tanto, la generación automática es una bendición para los desarrolladores y los usuarios finales.

Hemos cubierto algunos de los mejores generadores y exploradores de documentación GraphQL que hemos encontrado para darle una idea de lo que hay y elegir la herramienta perfecta para sus necesidades específicas. Todas estas herramientas lo ayudarán a aprovechar GraphQL al máximo. No perderá tiempo revisando los archivos de documentación. No tendrá que escribir páginas y páginas de documentación. Te liberará para hacer lo que realmente estás aquí para hacer, escribir código limpio y claro y crear aplicaciones excelentes.

Publicar un comentario

0 Comentarios