Graphql-tools: How to set a description to a type in GraphQL-tools?

[seklyza]

[stubailo]

Add a comment above the thing you are documenting:

# Description for the type
type MyObjectType {
  # Description for field
  myField: String!

  otherField(
    # Description for argument
    arg: Int
  )
}

Mind sending a PR to the docs about it? Probably worth adding a new section about descriptions around here: http://dev.apollodata.com/tools/graphql-tools/generate-schema.html#schema-language

[Shahor]

The # Description for the type won't work in the graphiql tools.
Is that because of a bug and the description isn't set on MyObjectType or a bug with graphiql?

[stubailo]

Do you have an example where it doesn't work?

[Shahor]

My bad, I was joining the schema from different files and didn't join on \n.

I ended up having a schema that looked like this :

type Something {
    id : ID
} # Some description
type Another {
    id : ID
}

And it seemed to confuse graphiql enough to not display those comments, but still work.

[linonetwo]

How to add the description using js?
I'm putting descriptions in a headless CMS and can get descriptions by REST API. So those descriptions are async data, and can only be loaded by JS.

[linonetwo]

Maybe I should use https://www.apollographql.com/docs/graphql-tools/schema-transforms.html to do this?

[linonetwo]

Oh, I can simply:

blockNum: {
    description: async () => 'some description about field blockNum',
}

[mearns]

@linonetwo, why would the description be async?

[linonetwo]

@mearns Each field have its translation and meaning explanations in a headless CMS.

But surely those translations can be download at build time. But to use downloaded translation, I still need to:

blockNum: {
    description () => translations.blockNum,
}

[alastairmccormack]

As of June 2018, descriptions are similar to Python docstrings - they simply use strings or stringblocks above the thing you want to document.

Example from: http://facebook.github.io/graphql/June2018/#example-64e5a

"""
A simple GraphQL schema which is well described.
"""
type Query {
  """
  Translates a string from a given language into a different language.
  """
  translate(
    "The original language that `text` is provided in."
    fromLanguage: Language

    "The translated language to be returned."
    toLanguage: Language

    "The text to be translated."
    text: String
  ): String
}