Document a GraphQL API

Question

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

Answer 1

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:

Altair: