GraphQL Schema Language 中の description がコメントから block string に変わった

graphql-tools の makeExecutableSchema のコードを読んでいて commentDescription なる項目が気になり、さらに utilities/buildASTSchema.js を見ていて

export type BuildSchemaOptions = {
  ...GraphQLSchemaValidationOptions,

  /**
   * Descriptions are defined as preceding string literals, however an older
   * experimental version of the SDL supported preceding comments as
   * descriptions. Set to true to enable this deprecated behavior.
   *
   * Default: false
   */
  commentDescriptions?: boolean,
};

と、description の書き方が変わったらしいことに気がつきました。

https://github.com/graphql/graphql-js/issues/1245 によると graphql@0.12.0 から GraphQL Schema Language 中の description の書き方がコメントから block string というものになっていたらしいです。

簡単に GraphQLSchema を printSchema して確認してみました。

import { GraphQLSchema, GraphQLObjectType, GraphQLString, printSchema } from 'graphql'

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'rootQuery',
    description: 'This is Root Query',
    fields: {
      hello: {
        type: GraphQLString,
        description: 'Greeting',
      },
    },
  }),
})

というスキーマを用意して

console.log(printSchema(schema))

とすると

schema {
  query: rootQuery
}

"""This is Root Query"""
type rootQuery {
  """Greeting"""
  hello: String
}

という """ で囲まれた block string による description が得られます。

今まで通りのコメントによる description を得るには commentDescription という後方互換性のためのオプションが用意されているので

console.log(printSchema(schema, { commentDescriptions: true }))

とすると

schema {
  query: rootQuery
}

# This is Root Query
type rootQuery {
  # Greeting
  hello: String
}

と今までどおりの形式で得られます。