GraphQL スキーマ仕様: 型やフィールドに説明文 (description) を記述する

GraphQL スキーマで定義する型には、Python の docstring と同様のフォーマットで description というドキュメントを付加できます。 description は型の直前、あるいはフィールドの直前に、3 つのクォート (""") で囲む形で記述します。

"""
Represents an auto-merge request for a pull request
"""
type AutoMergeRequest {
  """
  The email address of the author of this auto-merge request.
  """
  authorEmail: String

  """
  The commit message of the auto-merge request. If a merge queue is required by
  the base branch, this value will be set by the merge queue when merging.
  """
  commitBody: String

  ...
}

"""The root query entry point for the API"""
type Query {
  """The current time in ISO UTC"""
  currentTime: String
}

GraphQL スキーマ内の description はただのコメントではなく、その型のプロパティとして扱われ、GraphiQL などの各種ツールがその情報を参照して利用します。 GraphQL スキーマの型名やフィールド名だけで表現できる情報は限られているので、ほぼすべての型、フィールドに対して description を設定するのはよいプラクティスです。 下記は GitHub の GraphQL API のスキーマです。 description の記述方法の参考になります。

• https://docs.github.com/public/schema.docs.graphql

description の記述には Markdown（CommonMark 形式）が使えるようになっていますが、様々なツールから参照されることを考えると、あまり複雑な装飾はしない方が無難ですし、通常はそれで十分です。 フィールド変数を等幅フォントで表示するために、バッククォート (`) で囲んでおくくらいはやっておくとよさそうです。

関連記事

• GraphQL クエリ仕様: ディレクティブによる条件分岐 (@include, @skip)
• GraphQL クエリ仕様: フィールド名にエイリアスを付ける
• GraphQL スキーマ仕様: @deprecated ディレクティブで非推奨のフィールドを示す
• GraphQL スキーマ仕様: インタフェース型 (interface type) を定義する
• GraphQL スキーマ仕様: スキーマ定義の基本
• Apollo Client の fetchMore を自動で呼び出して GitHub GraphQL の100件制限を乗り越える (useAutoFetchMore)
• Apollo CLI の codegen で GraphQL クエリレスポンスの TypeScript 型を自動生成する