06_adding_descriptions.md

title	summary
Adding descriptions	Add descriptions to just about anything in your schema to improve your developer experience

Working with generic types

[CHILDREN asList]

[info] You are viewing docs for silverstripe/graphql 4.x. If you are using 3.x, documentation can be found in the github repository [/info]

Adding descriptions

One of the great features of a schema-backed API is that it is self-documenting. If you use the silverstripe/graphql-devtools module you can see the documentation by navigating to /dev/graphql/ide in your browser anc clicking on "DOCS" on the right.

Many API developers choose to maximise the benefit of this by adding descriptions to some or all of the components of their schema.

The trade-off for using descriptions is that the YAML configuration becomes a bit more verbose.

Let's add some descriptions to our types and fields.

app/_graphql/schema.yml

types:
  Country:
    description: A record that describes one of the world's sovereign nations
    fields:
      code:
        type: String!
        description: The unique two-letter country code
      name:
        type: String!
        description: The canonical name of the country, in English

We can also add descriptions to our query arguments. We'll have to remove the inline argument definition to do that.

app/_graphql/schema.yml

queries:
  readCountries:
    type: '[Country]'
    description: Get all the countries in the world
    args:
      limit:
        type: Int = 20
        description: The limit that is applied to the result set

Further reading

[CHILDREN]