Autogenerate Your GraphQL Documentation With Magidoc

GraphQL is an API technology that is rapidly gaining popularity among thousands of enterprises around the world. It was built to improve many aspects of REST, one of them being that GraphQL provides a native way to expose an API schema. This schema makes it easier than ever to generate API documentation with little effort.

Introducing Magidoc

Magidoc is an open source tool that can be used to easily autogenerate static GraphQL documentation for any GraphQL API, either from SDL files or from a live endpoint using the introspection query.

Not only can you use Magidoc to generate beautiful and easy to understand API documentation out of the box, but you can also provide custom pages using markdown. These pages allow you to present your API however you want. For instance, you could describe different concepts, examples, flows, URLs, etc.

Getting started

Schema (SDL)

First, we need a schema. For the sake of this demonstration, let’s use a simple TODO application schema. In a file named schema.graphqls, we will put the following code.

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

Then, we need a Magidoc configuration file. Magidoc uses configuration as code, which means that the configuration is nothing more than a Javascript file. This allows you to implement logic in it. For our example, let’s write the following configuration in a file called 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)
`
      }],
    },
  },
}

In this example, we load our schema from an SDL file. We also configure different website options, like the appTitle, appLogo and a custom page that contains markdown that will be rendered by Magidoc in the output website.

Build it

Finally, to build our website, we’ll execute the following commands:

npm install --global @magidoc/cli@latest
magidoc generate
magidoc preview

These commands will install Magidoc, generate the website and then preview the output locally.

And there you have it! A static GraphQL API documentation.

Conclusion

Magidoc is a powerful tool that can help you build superior GraphQL documentation very easily. This tutorial only scratches the surface of all that is possible to do with Magidoc. Many more advanced features exist, like a development server with hot-reload, the ability to provide custom assets (images or videos), full customization of the template using Svelte & Svelte-Kit, and many more built-in customization.

Make sure to check out the documentation to learn how you can turn your GraphQL schema into branded documentation website for your company, and have a look at the Github repository if you’re interested in contributing.

Thank you for reading!