Документ API GraphQL

Ответ 1

Похоже, теперь есть https://www.npmjs.com/package/graphql-docs

Динамически созданный проводник документации для схем GraphQL. Он призван обеспечить лучший обзор схемы, чем GraphiQL, но без запросов.

Вы также можете создать статический файл документации на основе файла схемы или конечной точки GraphQL:

npm install -g graphql-docs
graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html

Ответ 2

Насколько мне известно, еще нет инструмента, который автоматически генерирует HTML-документацию для API GraphQL, но я считаю, что GraphiQL даже более полезен, чем любая документация по API в HTML, которую я видел.

GraphiQL позволяет в интерактивном режиме исследовать схему сервера GraphQL и одновременно выполнять запросы к ней. Он имеет подсветку синтаксиса, автозаполнение и даже сообщает вам, когда ваш запрос недействителен без его выполнения.

Если вы ищете статическую документацию, мне показалось довольно удобным читать схему на языке схем GraphQL. Благодаря еще одной замечательной функции GraphQL - интроспекции схемы - вы можете легко распечатать схему для любого сервера, к которому у вас есть доступ. Просто запустите запрос самоанализа к серверу, а затем напечатайте полученную схему самоанализа следующим образом (используя graphql-js):

var graphql = require('graphql');
var introspectionSchema = {}; // paste schema here
console.log(graphql.printSchema(graphql.buildClientSchema(introspectionSchema)));

Результат будет выглядеть примерно так:

# An author
type Author {
  id: ID!

  # First and last name of the author
  name: String
}

# The schema root query type
type Query {

  # Find an author by name (must match exactly)
  author(name: String!): Author
}

Ответ 3

Я нашел генератор статических страниц для документирования схемы GraphQL. Ссылка на GitHub.

Экспорт в HTML выглядит следующим образом.

Пример документа GitHub GraphQL

Ответ 4

На самом деле Graphql вполне документируется с помощью встроенного в Facebook Graphiql или стороннего инструмента, такого как Altair потому что запросы/мутации перечислены и типы возврата также показаны там.

Одно место, где я нашел документ, это параметр запроса ввода, который может требовать specific format. Это может быть достигнуто путем добавления комментария поверх этих arguments.

  type Query {
      eventSearch(
        # comma separated location IDs. (eg: '5,12,27')
        locationIds: String,
        # Date Time should be ISO 8601: 'YYYY-DD-MM HH:mm:ss'. (eg: '2018-04-23 00:00:00')
        startDateTime: String!,
        endDateTime: String!): [Event]
  }

Это будет как ниже:

Graphiql:

Альтаир:

Ответ 5

Если вы являетесь пользователем Sphinx/ReadTheDocs, вы можете найти https://github.com/hasura/sphinx-graphiql полезным.