CODEWITHSUNDEEP
graphqlgraphql-js
Francisco Canela
Francisco Canela

Reputation: 1124

Document a GraphQL API

With REST we can use Swagger, RAML or other technologies to document our API and generate an HTML documentation that our consumers can read without any need of interaction with the servers.

Does something similar exist for GraphQL? Is there any way to generate a documentation of resources and properties?

Upvotes: 79

Views: 56432

Answers (8)

Aleksandr Vinokurov
Aleksandr Vinokurov

Reputation: 306

Can be added to the list: https://github.com/anvilco/spectaql

SpectaQL is a Node.js library that generates static documentation for a GraphQL schema

Upvotes: 0

Sunny Pelletier
Sunny Pelletier

Reputation: 379

There is now Magdoc too, a new tool that can generate static GraphQL documentation websites for any API using either introspection query or sdl files.

This is the GitHub repository, and docs are available at https://magidoc.js.org

Upvotes: 0

pylipp
pylipp

Reputation: 185

Another recent tool is SpectaQL. The output can look like this. Quoting from the README:

Autogenerate static GraphQL API documentation.

SpectaQL is a Node.js library that generates static documentation for a GraphQL schema using a variety of options:

  1. From a live endpoint using the introspection query.
  2. From a file containing an introspection query result.
  3. From a file, files or glob leading to the schema definitions in SDL.

The goal of SpectaQL is to help you keep your documentation complete, current and beautiful with the least amount of pain as possible.

Out of the box, SpectaQL delivers a 3-column page with a modern look and feel. However, many aspects can be customized with ease, and just about everything can be customized if you're willing to dig in.

Upvotes: 5

Alastair McCormack
Alastair McCormack

Reputation: 27744

If you're a Sphinx / ReadTheDocs User, you may find https://github.com/hasura/sphinx-graphiql useful.

Upvotes: 1

LeOn - Han Li
LeOn - Han Li

Reputation: 10234

Actually Graphql is quite self documented with Facebook's built-in Graphiql or the 3rd party tool like Altair because the queries/mutations are listed and return types are also shown there.

One place I found need doc is the input query parameter which might require specific format. This can be achieved by adding a comment on top of those 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]
  }

It will be like below:

Graphiql:

Graphiql

Altair:

Altair

Upvotes: 13

Zdeněk Dušátko
Zdeněk Dušátko

Reputation: 328

I found Static page generator for documenting GraphQL Schema. GitHub link.

HTML export looks like this.

GitHub GraphQL doc example

Upvotes: 17

jun
jun

Reputation: 789

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.

enter image description here

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

Upvotes: 36

helfer
helfer

Reputation: 7182

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
}

Upvotes: 26

Related Questions