Schema Descriptions

[vladinator1000]

Hello guys, I'm trying to find a way to include schema descriptions (the ones that pop out in Graphiql)

I know the graphql-js way, but couldn't figure out how to do it in Apollo.

var PlanetType = new GraphQLObjectType({
  name: 'Planet',
  description: // <----------- this thing
`A large mass, planet or planetoid in the Star Wars Universe, at the time of
0 ABY.`,
  fields: () => { }
})

[helfer]

The GraphQL schema language doesn't support descriptions at the moment (only deprecation, via decorators), but you can do it via resolvers. Check out this test to see how it works: https://github.com/apollostack/graphql-tools/blob/00d01eba94e8dbd21973e71b3cfd4361fdd8961d/test/testSchemaGenerator.js#L389

If you want to set a description on a type (as opposed to a field), you can do that by adding a __description field on the type (in resolvers, not in the schema). I know it's not ideal, but it's a temporary solution until a description PR (graphql/graphql-js#427) is merged in GraphQL.js

[vladinator1000]

That doesn't seem bad, thanks!

[vladinator1000]

Also, thank you so much for the lightning responses Jonas, you're awesome!

[lorensr]

This was added in graphql/graphql-js#464

and now works as a # comment in the schema string:

https://github.com/apollostack/GitHunt-API/blob/master/api/schema.js#L9

[kirill-konshin]

I found a weird behavior, probably it deserves another bug, but I think I should start here.

When schema definition is wrapped in gql template all the descriptions are lost. It does not matter if the string is inlined or loaded from a file.

I am using apollo-server-express@2.3.1, here's the part of schema:

type PlaylistShort implements PlaylistInterface {
    # integer ID: 123 (RO)
    id: ID!
    # playlist title: "S-Bahn Sounds" (RW)
    title: String
    # (RW)
    tracks: [TrackShort]
}

And here's what is returned by introspection query:

All description fields are empty...

Apollo server creation code:

const typeDefs = readFileSync(path.join(__dirname, 'src', 'apollo', 'schema.graphqls')).toString();

export const apolloServer = new ApolloServer({
    typeDefs: gql`${typeDefs}`,
    resolvers,
    introspection: true,
    tracing: true,
    context: ({req}) => ({
        authHeader: req.headers['authheader']
    })
});

If I replace

typeDefs: gql`${typeDefs}`

... with

typeDefs: typeDefs,

... it starts to work as expected.

[wszgxa]

same issue with @kirill-konshin ... don't know it's designed by that or it's an issue.

Could we create another issue for this?