GraphQL — действительно мощная технология, созданная Facebook еще в 2012 году и выложенная в открытый доступ в 2015 году. Она отличается от REST по многим аспектам, решая проблемы выборки и недовыборки. Поскольку GraphQL управляется схемой, он также позволяет автоматически документировать API через схему.
В частности, уже давно существуют динамические инструменты, такие как Altair или GraphiQL, которые позволяют вам играть с API и легко писать запросы. Эти инструменты, безусловно, очень полезны, но действительно ли они все, что вам нужно для документирования вашего API?
Статическая документация
Нельзя отрицать, игровые площадки GraphQL полезны и определенно должны быть частью вашего набора инструментов для документации. Однако вашим пользователям недостаточно иметь полное представление о том, что может сделать ваш API. Среди прочего, игровые площадки не имеют возможности представлять URL-адреса, потоки аутентификации, контексты, примеры, учебные пособия или даже ваш бизнес-домен. Эти инструменты созданы для взаимодействия с вашим API, а не для его документирования.
Именно здесь вступает в действие статическая документация. Magidoc — это генератор статической документации для GraphQL, что означает, что он позволяет вам создавать веб-сайт для любого API, используя либо запрос самоанализа, либо файлы SDL, и с очень минимальным объемом. работы.
Создайте свой первый веб-сайт
Начать работу с Magidoc очень просто. Вы можете ознакомиться с полной документацией здесь, если вам нужно.
Схема
Первое, что нам нужно, это схема. Итак, давайте создадим его! Мы создаем новый файл с именем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.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) ` }], }, }, }
Построить это!
Почти готово (да, уже). Последний шаг — установить и запустить Magidoc. Вы можете либо установить его глобально, либо запустить напрямую с помощью 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
Это должно дать вам что-то вроде этого:
И вот, у вас есть веб-сайт документации!
Наиболее интересным аспектом выходной документации является возможность динамически генерировать запросы.
Узнать больше
Эта демонстрация лишь поверхностно показывает, что вы можете делать с Magidoc. Его основная цель - предоставить простой способ настроить вывод и создать все, что вы хотите, если вам нужно.
Обязательно загляните в репозиторий GitHub, если он вам нравится, и ознакомьтесь с документацией, чтобы узнать больше о том, что Magidoc может сделать для вас.
Спасибо за прочтение и берегите себя✌️