paint-brush
Autogenerate Your GraphQL Documentation With Magidocby@pelletier197
8,424 reads
8,424 reads

Autogenerate Your GraphQL Documentation With Magidoc

by Sunny Pelletier3mJune 29th, 2022
Read on Terminal Reader
Read this story w/o Javascript
tldt arrow

Too Long; Didn't Read

Magidoc is an open source tool that can be used to easily autogenerate static GraphQL documentation for any GraphQL API. Learn how you can generate a GraphQL documentation website in a few minutes with Magidoc.

Company Mentioned

Mention Thumbnail
featured image - Autogenerate Your GraphQL Documentation With Magidoc
Sunny Pelletier HackerNoon profile picture

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.


Magidoc supports advanced markdown features like tables, ordered and unordered lists, inline HTML and much more.

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.

Example of website

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!