Avec REST, nous pouvons utiliser Swagger, RAML ou d'autres technologies pour documenter notre API et générer une documentation HTML que nos consommateurs peuvent lire sans avoir besoin d'interagir avec les serveurs.
Existe-t-il quelque chose de similaire pour GraphQL ? Existe-t-il un moyen de générer une documentation des ressources et des propriétés ?
Il semble qu'il y ait maintenant https://www.npmjs.com/package/graphql-docs
Explorateur de documentation généré dynamiquement pour les schémas GraphQL. Il vise à fournir une meilleure vue d'ensemble d'un schéma que GraphiQL, mais sans fonctionnalités d'interrogation.
Vous pouvez également générer un fichier de documentation statique basé sur un fichier de schéma ou un point de terminaison GraphQL :
npm install -g graphql-docs
graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html
À ma connaissance, il n'existe pas encore d'outil permettant de générer automatiquement une documentation HTML pour une API GraphQL, mais j'ai trouvé GraphiQL est encore plus utile que toute documentation d'API en HTML que j'ai vue.
GraphiQL vous permet d'explorer de manière interactive le schéma d'un serveur GraphQL et d'exécuter des requêtes contre lui en même temps. Il dispose de la coloration syntaxique, de l'autocomplétion et vous indique même si votre requête est invalide sans l'exécuter.
Si vous recherchez une documentation statique, j'ai trouvé assez pratique de lire le schéma dans le langage de schéma GraphQL. Grâce à une autre grande fonctionnalité de GraphQL - l'introspection de schéma - vous pouvez facilement imprimer le schéma de tout serveur auquel vous avez accès. Il suffit d'exécuter la commande requête d'introspection contre le serveur et ensuite imprimer le schéma d'introspection résultant comme suit (en utilisant graphql-js) :
var graphql = require('graphql');
var introspectionSchema = {}; // paste schema here
console.log(graphql.printSchema(graphql.buildClientSchema(introspectionSchema)));Le résultat ressemblera à ceci :
# 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
}
Merci, helfer. L'inconvénient d'utiliser l'API comme documentation est que le développeur en a parfois besoin avant d'y avoir accès. Par exemple : Quand on décide d'acheter un service d'API. Vous avez fourni une alternative intéressante à cette mise en garde. Merci pour cette réponse utile. Je vais attendre un peu et la marquer comme acceptée si rien de mieux ne vient.
J'ai trouvé un générateur de pages statiques pour documenter le schéma GraphQL. Lien GitHub .
L'exportation HTML ressemble à ceci.
En fait, Graphql est assez bien documenté grâce à l'interface intégrée de Facebook. Graphiql ou un outil tiers comme Altair car les requêtes/mutations sont listées et les types de retour y sont également indiqués.
Un endroit où j'ai trouvé un besoin de documentation est le paramètre de la requête d'entrée qui pourrait nécessiter specific format . Ceci peut être réalisé en ajoutant un commentaire sur le dessus de ceux 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]
}Ce sera comme ci-dessous :
Si vous êtes un utilisateur de Sphinx / ReadTheDocs, vous trouverez peut-être que https://github.com/hasura/sphinx-graphiql utile.
Prograide est une communauté de développeurs qui cherche à élargir la connaissance de la programmation au-delà de l'anglais.
Pour cela nous avons les plus grands doutes résolus en français et vous pouvez aussi poser vos propres questions ou résoudre celles des autres.
