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 может сделать для вас.

Спасибо за прочтение и берегите себя✌️