Autogenerate GraphQL documentation with Magidoc

GraphQL is a really powerful technology that was created by Facebook back in 2012 and made publicly available in 2015. It differs from REST on many aspects, solving problems of over and under-fetching. GraphQL being schema-driven, it also enables auto-documentation of APIs through the schema.

In particular, dynamic tools like Altair or GraphiQL have been around for a while and allow you to play with APIs and write queries easily. These tools are definitely super useful, but are they actually all you need to document your API?

Static documentation

There is no denying it, GraphQL playgrounds are useful and should definitely be part of your documentation tool set. However, it is not enough for your users to have a full grasp of what your API can do. Among other things, playgrounds lack the ability to present URLs, authentication flows, contexts, examples, tutorials or even your business domain. These tools are made to interact with your API, not to document it.

This is where static documentation steps in. Magidoc is a static documentation generator for GraphQL, meaning that it enables you to generate a website for any API using either an introspection query or SDL files, and with a very minimal amount of work.

Create your first website

Getting started with Magidoc is super simple. You can check out the full documentation here if you need to.

Schema

First thing we need is a schema. So let’s create one! We create a new file namedschema.graphqls and add the following content.

type Todo {
  id: ID
  name: String
  complete: Boolean
}
input TodoInput {
  todoId: ID
  name: String
  complete: Boolean
}
type Query {
  """
  Returns all `TODOs` 
  """
  todos: [Todo]
  """
  Return a specific `TODO` by ID. 
  """
  todo(todoId: ID): Todo
}
type Mutation {
  """
  Creates a `TODO` and returns it.
  """
  createTodo(input: TodoInput!): Todo
  """
  Updates a `TODO` or returns an error if it does not exist.
  """
  updateTodo(input: TodoInput!): Todo
  """
  Toggles a `TODO` or returns an error if it does not exist.
  """
  toggleTodo(todoId: ID!): Todo
  """
  Deleted a `TODO` or returns an error if it does not exist.
  """
  deleteTodo(input: TodoInput!): [Todo]
}

Magidoc configuration

Now that we have our schema, we can create a Magidoc configuration file. We will use the following configuration that we put in a file named magidoc.mjs .

export default {
  introspection: {
    type: 'sdl',
    paths: ['./schema.graphqls'],
  },
  website: {
    template: 'carbon-multi-page',
    options: {
      appTitle: 'Medium Article',
      appLogo: 'https://seeklogo.com/images/P/Pokemon-logo-497D61B223-seeklogo.com.png',
      pages: [{
        title: 'Medium Article',
        content: `
# Medium Article
Congratulations! You've successfully completed the Magidoc tutorial.
## Where to go next?
- Star the project on [GitHub](https://github.com/magidoc-org/magidoc) 
- Read the [documentation](https://magidoc.js.org/introduction/welcome)
`
      }],
    },
  },
}

Build it!

Almost there (yes, already). Last step is to install and run Magidoc. You can either install it globally or run it directly with npx.

# Either install it globally
pnpm install --global @magidoc/cli
magidoc generate
magidoc preview
# Or use npx
npx @magidoc/cli@latest generate
npx @magidoc/cli@latest preview

This should give you something like this:

And there you are, you have a documentation website!

Website output

The most interesting aspect of the output documentation is the ability to generate queries dynamically.

Query generator

Learn more

This demonstration only scratches the surface of what you can do with Magidoc. Its main purpose is to provide an easy way to customise the output and to build anything you want if you need to.

Make sure to have a look at the GitHub repository if you like it and check out the documentation to know more about what Magidoc can do for you.

Thanks for reading and stay safe✌️