Документ API GraphQL

С помощью REST мы можем использовать Swagger, RAML или другие технологии для документирования нашего API и создания HTML-документации, которую наши потребители могут читать без необходимости взаимодействия с серверами.

Что-то похожее для 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
}

Ответ 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:

Graphiql

Альтаир:

Altair