graphql - graphiql
Documentar una API GraphQL (4)
Con REST podemos usar Swagger, RAML u otras tecnologías para documentar nuestra API y generar una documentación HTML que nuestros consumidores puedan leer sin necesidad de interacción con los servidores.
¿Hay algo similar para GraphQL? ¿Hay alguna forma de generar una documentación de recursos y propiedades?
En realidad, Graphql está bastante auto documentado con Graphiql integrado en Graphiql o la herramienta de terceros como Altair ya que las consultas / mutaciones se enumeran y los tipos de devolución también se muestran allí.
Un lugar que encontré que necesita doc es el parámetro de consulta de entrada que puede requerir specific format . Esto se puede lograr agregando un comentario encima de esos arguments .
type Query {
eventSearch(
# comma separated location IDs. (eg: ''5,12,27'')
locationIds: String,
# Date Time should be ISO 8601: ''YYYY-DD-MM HH:mm:ss''. (eg: ''2018-04-23 00:00:00'')
startDateTime: String!,
endDateTime: String!): [Event]
}
Será como a continuación:
Graphiql:
Altair:
Encontré el generador de páginas estáticas para documentar el esquema GraphQL. Enlace GitHub .
La exportación HTML se ve así.
Parece que ahora hay https://www.npmjs.com/package/graphql-docs
Documentación generada dinámicamente del explorador para esquemas GraphQL. Su objetivo es proporcionar una mejor visión general de un esquema que GraphiQL, pero sin consultar las características.
También puede generar un archivo de documentación estática basado en un archivo de esquema o punto final GraphQL:
npm install -g graphql-docs
graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html
Que yo sepa, todavía no hay ninguna herramienta que genere automáticamente la documentación HTML para una API GraphQL, pero he encontrado que GraphiQL es incluso más útil que cualquier documentación API en HTML que he visto.
GraphiQL permite explorar de forma interactiva el esquema de un servidor GraphQL y ejecutar consultas contra él al mismo tiempo. Tiene resaltado de sintaxis, autocompletado e incluso le dice cuándo su consulta no es válida sin ejecutarla.
Si está buscando documentación estática, he encontrado que es muy conveniente leer el esquema en el lenguaje de esquema GraphQL. Gracias a otra gran característica de GraphQL (introspección de esquema), puede imprimir fácilmente el esquema para cualquier servidor al que tenga acceso. Simplemente ejecute la consulta de introspección en el servidor y luego imprima el esquema de introspección resultante de este modo (utilizando graphql-js):
var graphql = require(''graphql'');
var introspectionSchema = {}; // paste schema here
console.log(graphql.printSchema(graphql.buildClientSchema(introspectionSchema)));
El resultado se verá algo así:
# An author
type Author {
id: ID!
# First and last name of the author
name: String
}
# The schema''s root query type
type Query {
# Find an author by name (must match exactly)
author(name: String!): Author
}