GraphQL是一种API技术，在全世界成千上万的企业中迅速普及。它的建立是为了改进REST的许多方面，其中之一是GraphQL提供了一种暴露API模式的本地方式。这种模式使生成API文档比以往任何时候都更容易，只需很少的努力。
介绍一下Magidoc
Magidoc是一个开源工具，可以用来为任何GraphQL API轻松地自动生成静态GraphQL文档，无论是从SDL文件还是从使用自省查询的实时端点。
你不仅可以使用Magidoc来生成漂亮的、易于理解的API文档，而且还可以使用markdown提供自定义页面。这些页面允许你以你想要的方式展示你的API。例如，你可以描述不同的概念、例子、流程、URL等。
如果你有兴趣看到更多的可能性，请看一下演示网站。
开始使用
模式(SDL)
首先，我们需要一个模式。为了这个演示，让我们使用一个简单的TODO应用模式。在一个名为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配置
然后，我们需要一个Magidoc配置文件。Magidoc使用配置作为代码，这意味着配置只不过是一个Javascript文件。这允许你在其中实现逻辑。对于我们的例子，让我们在一个名为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-org.github.io/magidoc/introduction/welcome)
`
}],
},
},
}
在这个例子中，我们从一个SDL文件加载我们的模式。我们还配置了不同的网站选项，比如appTitle 、appLogo ，以及一个包含markdown的自定义页面，该页面将由Magidoc在输出网站中呈现。
Magidoc支持高级的markdown功能，如表格、有序和无序的列表等等。
建立它
最后，为了建立我们的网站，我们将执行以下命令。
npm install --global @magidoc/[email protected]
magidoc generate
magidoc preview
这些命令将安装Magidoc，生成网站，然后在本地预览输出。
输出的例子
就这样，你拥有了它!一个静态的GraphQL API文档。
总结
Magidoc是一个强大的工具，可以帮助你非常容易地建立卓越的GraphQL文档。这个教程只是触及了Magidoc所有可能做的事情的表面。还有许多更高级的功能，如带有热重载的开发服务器，提供自定义资产（图片或视频）的能力，使用Svelte和Svelte-Kit完全定制模板，以及更多的内置定制功能。
请务必查看文档，了解如何将你的GraphQL模式变成你公司的品牌文档网站，如果你有兴趣贡献，请访问Github仓库。
l o a d i n g
. ..评论及更多!
