web-dev-qa-db-ja.com

GraphQL APIを文書化する

RESTを使用すると、Swagger、RAML、またはその他のテクノロジーを使用してAPIを文書化し、消費者がサーバーと対話することなく読むことができるHTMLドキュメントを生成できます。

GraphQLには似たようなものがありますか？リソースとプロパティのドキュメントを生成する方法はありますか？

graphqlgraphql-js
47
Francisco Canela

今あるように見えます https://www.npmjs.com/package/graphql-docs

GraphQLスキーマ用の動的に生成されたドキュメントエクスプローラー。 GraphiQLよりもスキーマの概要を提供することを目的としていますが、クエリ機能はありません。

enter image description here

スキーマファイルまたはGraphQLエンドポイントに基づいて静的なドキュメントファイルを生成することもできます。

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

私の知る限り、GraphQL APIのHTMLドキュメントを自動的に生成するツールはまだありませんが、 GraphiQL は、私が見たHTMLのどのAPIドキュメントよりもさらに便利であることがわかりました。

GraphiQL を使用すると、GraphQLサーバーのスキーマをインタラクティブに探索し、同時にクエリを実行できます。構文の強調表示、オートコンプリートがあり、クエリが実行されずに無効な場合も通知されます。

静的なドキュメントを探しているなら、GraphQLスキーマ言語でスキーマを読むのが非常に便利だとわかりました。 GraphQLの別の優れた機能であるスキーマイントロスペクションのおかげで、アクセスできるサーバーのスキーマを簡単に印刷できます。サーバーに対して introspection query を実行し、結果のイントロスペクションスキーマをそのように出力します（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's root query type
type Query {

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

GraphQLスキーマを文書化するための静的ページジェネレーターを見つけました。 GitHubリンク 。

HTMLエクスポートは次のようになります。

GitHub GraphQL docの例

8
Zdeněk Dušátko

実際、GraphqlはFacebookの組み込みGraphiqlまたはAltairなどのサードパーティツールを使用して非常に自己文書化されています。クエリ/突然変異がリストされ、戻り値の型も表示されるためです。

Docが必要だとわかった場所の1つは、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

6
LeOn - Han Li

あなたがSphinx/ReadTheDocsユーザーなら、 https://github.com/hasura/sphinx-graphiql が役に立つかもしれません。

0
Alastair McCormack