Document a GraphQL API

Solution 1:

It looks like there is now https://www.npmjs.com/package/graphql-docs

Dynamically generated documentation explorer for GraphQL schemas. It aims to provide a better overview of a schema than GraphiQL, but without querying features.

You can also generate a static documentation file based on a schema file or GraphQL endpoint:

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

Solution 2:

To my knowledge there is no tool yet that automatically generates HTML documentation for a GraphQL API, but I've found GraphiQL to be even more useful than any API documentation in HTML that I've seen.

GraphiQL lets you interactively explore the schema of a GraphQL server and run queries against it at the same time. It has syntax highlighting, autocompletion, and it even tells you when your query is invalid without executing it.

If you're looking for static documentation, I've found it pretty convenient to read the schema in GraphQL schema language. Thanks to another great feature of GraphQL - schema introspection - you can easily print the schema for any server you have access to. Simply run the introspection query against the server and then print the resulting introspection schema like so (using graphql-js):

var graphql = require('graphql');
var introspectionSchema = {}; // paste schema here
console.log(graphql.printSchema(graphql.buildClientSchema(introspectionSchema)));

The result will look something like this:

# 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
}