Documentación de las API de GraphQL

El objetivo principal de la documentación de la API es ayudar a los desarrolladores a comprender cómo usar una API.

Suponga que acaba de lanzar una nueva API y creó la documentación que otros desarrolladores pueden usar para comprender cómo funciona su API. Esta documentación generalmente se puede generar automáticamente si ha seguido una especificación de API como OpenAPI. Una excelente manera de escribir documentación es crear documentación estática con ejemplos de código interactivos, lo que ayudará a las personas a comenzar.

Sin embargo, la primera vez que usted (o sus usuarios) utilizan una API de GraphQL puede ser muy frustrante, ya que las API de GraphQL normalmente solo tienen un campo de juego interactivo. Este patio de recreo a menudo se crea con GraphiQL, un entorno de desarrollo interactivo (IDE), y sirve como la forma principal de documentación para la mayoría de las API de GraphQL. Con GraphiQL, puede explorar el esquema de la API, componer operaciones de GraphQL y ejecutarlas para obtener una respuesta. Una desventaja de tener solo este IDE es que aumenta la complejidad para los recién llegados a GraphQL, ya que supone que ya está familiarizado con GraphQL.

Pero con GraphQL, no está limitado a solo un área de juegos interactiva, ya que puede crear documentación estática o interactiva además de tener este área de juegos. Este artículo explora qué formas de documentación puede usar y cómo agregan valor a su API de GraphQL.

Uso de la introspección para explorar GraphQL

Cualquier forma de documentación que escriba para una API de GraphLQ comienza con algo llamado introspección. Con la introspección, obtiene más información sobre el esquema de una API de GraphQL, sus tipos y las posibles operaciones. Usando una consulta de introspección de GraphQL, la API responderá con detalles sobre el punto final de GraphQL que está introspeccionando.

Una consulta de introspección se verá así:

 { __schema { queryType { name } } }

Esta consulta devolverá todas las consultas posibles que puede ejecutar con esta API de GraphQL y, como se ejecuta directamente en el servidor, se actualizará a medida que el esquema cambie con el tiempo. La introspección se puede usar directamente desde la terminal mediante una solicitud curl. Esta es una forma muy básica pero eficiente de descubrir cómo puede usar una API de GraphQL y qué operaciones y tipos son compatibles.

El uso de la introspección es parte de la especificación de GraphQL, pero la opción para usarla a menudo está deshabilitada para entornos de producción. Al permitir que todos introspeccionen su punto final, podría revelar información confidencial. Es por eso que la mayoría de las empresas no admiten la introspección, pero le permiten inspeccionar un GraphQL a través de un área de juegos como GraphiQL o solo documentación estática/interactiva.

Explorando GraphQL con GraphiQL

Acaba de enterarse de que puede obtener toda la información sobre un esquema de GraphQL, como consultas o mutaciones que puede ejecutar y los tipos que devolverán con una consulta de introspección. Pero como la introspección a menudo está deshabilitada en los puntos finales que se ejecutan en producción, las empresas utilizan el área de juegos de GraphiQL como alternativa. Cuando un área de juegos está disponible, la mayoría de las API de GraphQL le darán acceso cuando visite el punto final de la API en el navegador.

La API GraphQL de ejemplo que ve a continuación se creó con StepZen . Para cada punto final de GraphQL que cree con StepZen, puede acceder a un área de juegos de GraphiQL que se ve así:

GraphiQL es una excelente manera de explorar una API de GraphQL, ya que le permite interactuar con ella en un IDE. Este IDE le permite ver el esquema, hacer clic en las posibles operaciones y obtener más información sobre qué campos o tipos están disponibles. Con GraphiQL puedes enviar operaciones al servidor y ver qué respuesta generarán.

Al crear un esquema de GraphQL, también puede agregar descripciones para campos y tipos en el esquema, que se volverán visibles en GraphiQL. Aunque esto hace que la experiencia sea más completa, aún necesita saber cómo redactar una consulta con GraphQL para ver la respuesta de la API. El esquema que puede encontrar en GraphiQL es útil, pero si no está familiarizado con GraphQL, esto por sí solo no le llevará mucho más lejos.

Proporcione ejemplos en su documentación de GraphQL

La documentación debería ayudar a los desarrolladores a comprender cómo usar una API y, para GraphQL, tanto la introspección como el área de juegos de GraphiQL son buenos puntos de partida. Pero otro objetivo es mostrar a los desarrolladores cómo pasar de la documentación al código, mientras que la introspección y el patio de recreo solo brindan la parte de codificación. Para brindarles a los desarrolladores que usan su API GraphQL más contexto sobre cómo usarla para sus necesidades, algunas empresas eligen acompañar un patio de recreo con documentación estática o interactiva.

La documentación estática puede ser una buena adición, con un área de juegos que se ejecute en GraphiQL para que sea interactiva. La documentación estática puede brindarle al desarrollador toda la información sobre cómo componer operaciones, incluidos ejemplos de código, y leer la respuesta del patio de recreo más tarde. La combinación de documentación con ejemplos estáticos con un área de juegos de GraphiQL brinda a los desarrolladores todas las herramientas que necesitan para comenzar a usar su API, incluso sin saber cómo funciona GraphQL.

Otra cosa que hace que una buena documentación se destaque es estar actualizada. Si usa una consulta de introspección o un área de juegos para documentar su API de GraphQL, el motor de GraphQL se asegura de que siga cualquier cambio realizado en el esquema de la API. Si elige crear la documentación (estática) usted mismo, es importante mantenerla actualizada. Puede actualizarlo manualmente cuando publique una nueva función o integre CI/CD para generar nueva documentación para su API en la implementación.

Crear documentación estática para GraphQL

Además de usar la introspección o GraphiQL para documentar su API de GraphQL, también puede hacerlo de forma estática. Esto puede parecerle familiar si ha usado API REST en el pasado, ya que a menudo tienen documentación estática. Para crear documentación estática para su API GraphQL, puede usar una biblioteca como SpectaQL . La documentación estática que se generará se parece a la siguiente:

Esta biblioteca utiliza las consultas que proporciona para su API junto con su esquema para crear la documentación. Si ha agregado descripciones en su esquema, estas también se agregarán a la documentación. Paragenerar documentación estática para su GraphQL usando SDL , solo tiene que instalar spectaql desde npm y crear un archivo de configuración para definir dónde se puede encontrar su esquema:

 spectaql: logoFile: '' introspection: url: '' headers: Authorization: '' info: title: '' description: '' servers: - url: '' description: Production production: true

Esta configuración es todo lo que necesita para generar la documentación estática. La salida se puede alojar en cualquier servidor, ya que SpectaQL crea un paquete de JavaScript para usted.

Conclusión

Hemos explorado varias formas de documentar una API de GraphQL mediante una consulta de introspección, un campo de juego como GraphiQL o mediante documentación (interactiva). Todos estos enfoques utilizan el esquema GraphQL como entrada para generar la documentación. La documentación debe satisfacer las necesidades de los desarrolladores que desean usar su API y llevarlos de la documentación al código mediante ejemplos de código interactivos. Puede lograr exactamente eso mejorando las herramientas que GraphQL ya ofrece, como la consulta de introspección y GraphiQL.