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 , we will put the following code. schema.graphqls 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 , and a custom page that contains markdown that will be rendered by Magidoc in the output website. appTitle appLogo 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. 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 if you’re interested in contributing. Github repository Thank you for reading!

Different

2022 - HackerNoon Contributor of the Year - Graphql

Read My Stories

Nominated for 2022 - HackerNoon Contributor of the Year - Graphql

Too Long; Didn't Read

 Add passwordless user experiences to your app

HackerNoon Mobile

Autogenerate Your GraphQL Documentation With Magidoc

Too Long; Didn't Read

Company Mentioned

@pelletier197

RELATED STORIES