Saltar al contenido principal

​
Agrega un esquema de GraphQL

Para crear páginas para tu API de GraphQL, necesitas un esquema de GraphQL válido en formato SDL (Schema Definition Language). Almacena el esquema en tu repositorio de documentación o alójalo en una URL HTTPS que Mintlify pueda obtener.
schema.graphql

​
Generar automáticamente páginas de GraphQL

Para generar automáticamente páginas para cada consulta, mutación y tipo de tu esquema, agrega una propiedad graphql a una pestaña o a un grupo en tu docs.json. Mintlify analiza el esquema y crea una página para cada operación y tipo con nombre.
La propiedad graphql acepta ya sea una cadena (una ruta local o una URL HTTPS) o un objeto con los siguientes campos:
Solo puedes declarar graphql en una pestaña o en un grupo.Una pestaña con graphql puede incluir groups, pero ninguna otra estructura de navegación, como pages, versions o languages.Un grupo con graphql puede incluir pages.
​
string
requerido
Una ruta local a un archivo SDL en tu repositorio de documentación o una URL HTTPS a un archivo SDL alojado. No se aceptan URL HTTP.
​
string
El directorio donde se colocan las páginas generadas. El valor predeterminado es graphql-reference.

​
Páginas generadas

Mintlify organiza las páginas generadas en tres secciones dentro de la pestaña o el grupo que configuraste:
  • Queries — una página por cada campo de tu tipo raíz Query.
  • Mutations — una página por cada campo de tu tipo raíz Mutation.
  • Types — una página por cada tipo con nombre: object, input, enum, interface o union.
En una pestaña, las secciones aparecen después de los grupos que definas. En un grupo, aparecen como grupos anidados después de las páginas que enumeres. Cada página de operación muestra la descripción del campo, los argumentos, el tipo de retorno y enlaces a cualquier tipo referenciado. Las páginas de consultas y mutaciones también incluyen una operación de ejemplo generada, las variables requeridas y una respuesta JSON de muestra. Las páginas de tipos renderizan la definición del esquema en modo solo lectura, con los tipos de campo enlazados para que las personas que leen puedan navegar por el grafo.

​
Selecciona operaciones y tipos específicos

Para crear una referencia seleccionada en lugar de generar todas las páginas, enumera selectores en el array pages de un grupo que declare graphql. También puedes enumerarlos en cualquier grupo anidado dentro de una pestaña o un grupo que declare graphql. Las pestañas con graphql no pueden incluir pages, así que coloca los selectores en un grupo dentro de la pestaña. Mintlify genera una página solo para cada operación o tipo seleccionado.
Un selector es un tipo seguido de un nombre, separados por un espacio:
  • QUERY <field>: un campo de tu tipo raíz Query.
  • MUTATION <field>: un campo de tu tipo raíz Mutation.
  • TYPE <name>: un tipo con nombre: object, input, enum, interface o union.
Los tipos de selector deben estar en mayúsculas. Usa una ruta con puntos, como MUTATION cart.createCart, para seleccionar una operación anidada en un campo de espacio de nombres. Los selectores TYPE no aceptan rutas con puntos. La barra lateral muestra una operación anidada con su último segmento, por lo que MUTATION cart.createCart aparece como createCart. La URL de la página conserva la ruta completa y termina en cart/createCart. Si alguna página dentro de una pestaña o un grupo con graphql es un selector, Mintlify omite la generación de las secciones completas Queries, Mutations y Types para ese elemento. Las rutas de página normales en el mismo array pages funcionan como siempre. En una referencia seleccionada, las páginas de consultas y mutaciones enlazan solo a las páginas de tipos que generan tus selectores. Para enlazar un tipo referenciado por una operación seleccionada, agrega un selector TYPE para ese tipo. Si un selector no coincide con nada en tu esquema, la compilación falla con un error que indica la operación o el tipo que falta.

​
Deprecaciones

Los campos y argumentos marcados con @deprecated en tu esquema se señalan como obsoletos en las páginas generadas. El motivo de la deprecación, cuando se proporciona, aparece junto al campo.

​
Actualiza tu documentación

Mintlify regenera las páginas de referencia de GraphQL cuando ejecutas mint dev o cuando envías cambios a tu repositorio de documentación. Si tu esquema está alojado en una URL HTTPS, las actualizaciones del esquema se incorporan en la siguiente compilación.

Temas relacionados

Migrar desde otra plataformaSEOReferencia de comandos de la CLI de Mintlify