web-dev-qa-db-fra.com

Documenter une API GraphQL

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 aucune interaction avec les serveurs.

Existe-t-il quelque chose de similaire pour GraphQL? Est-il possible de générer une documentation de ressources et de propriétés?

graphqlgraphql-js
35
Francisco Canela

On dirait qu'il y a maintenant https://www.npmjs.com/package/graphql-docs

Documentation générée dynamiquement Explorer pour les schémas GraphQL. Il vise à fournir une meilleure vue d'ensemble d'un schéma que GraphiQL, mais sans interroger les fonctionnalités.

 enter image description here

Vous pouvez également générer un fichier de documentation statique basé sur un fichier de schéma ou un noeud final GraphQL:

npm install -g graphql-docs
graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html
22
jun

À ma connaissance, aucun outil n’a encore généré automatiquement de documentation HTML pour une API GraphQL, mais j’ai trouvé que GraphiQL était encore plus utile que toute documentation d’API en HTML déjà consultée.

GraphiQL vous permet d'explorer de manière interactive le schéma d'un serveur GraphQL et d'exécuter des requêtes sur celui-ci en même temps. Il a la coloration syntaxique, l'auto-complétion, et il vous indique même si votre requête est invalide sans l'exécuter.

Si vous recherchez une documentation statique, j'ai trouvé très pratique de lire le schéma en langage de schéma GraphQL. Grâce à une autre fonctionnalité intéressante de GraphQL - l'introspection de schéma - vous pouvez facilement imprimer le schéma de n'importe quel serveur auquel vous avez accès. Exécutez simplement la requête introspection sur le serveur, puis imprimez le schéma d’introspection obtenu comme suit (à l’aide de 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
}
12
helfer

J'ai trouvé le générateur de page statique pour documenter le schéma GraphQL. lien GitHub .

L'exportation HTML ressemble à ceci.

Exemple de doc GitHub GraphQL

8
Zdeněk Dušátko

En fait, Graphql est assez auto-documenté avec la variable Graphiql intégrée de Facebook ou l'outil tiers tel que Altair car les requêtes/mutations sont répertoriées et les types de retour y sont également indiqués.

Un endroit où j'ai trouvé besoin de doc est le paramètre de requête d'entrée qui pourrait nécessiter specific format. Ceci peut être réalisé en ajoutant un commentaire en plus 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:

Graphiql:

Graphiql

Altair:

Altair

4
Leon li

Si vous êtes un utilisateur Sphinx/ReadTheDocs, vous pouvez trouver https://github.com/hasura/sphinx-graphiql utile.

0
Alastair McCormack