c1cda2b113
* DOCS: Add new graphql 4 docs * Reorganise docs * Docs done * Basic graphql index page * TOC for getting started * show folders on graphql index page * Add middleware note * Docs update * Update docs to reflect flushless schema * Docs updates * Docs for getByLink * Query caching docs * Docs on nested operations * update docs for new graphql dev admin * Docs for configurable operations * Replace readSiteTrees with readPages * Schema defaults docs * Docs for inherited plugins * Docs for customising * * Docs for field whitelisting * Change whitelist word * New docs on modelConfig * Document dev/build extension * Document default/global plugins * Document new input type fields config * Apply suggestions from code review Co-authored-by: Andre Kiste <bergice@users.noreply.github.com> * Note about when procedural schema gets built * Fix link * Apply suggestions from code review Co-authored-by: Andre Kiste <bergice@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Andre Kiste <bergice@users.noreply.github.com> * DOCS Note about plugins in custom queries * DOCS Note about filter and custom resolvers * DOCS Note about canview paging * DOCS Updated guidance on _extend See https://github.com/silverstripe/silverstripe-graphql/issues/296 * Apply suggestions from code review Co-authored-by: Andre Kiste <bergice@users.noreply.github.com> * DOCS Pre-release warning Co-authored-by: Ingo Schommer <ingo@silverstripe.com> Co-authored-by: Andre Kiste <bergice@users.noreply.github.com> Co-authored-by: Ingo Schommer <me@chillu.com>
1.8 KiB
| title | summary |
|---|---|
| Adding descriptions | Add descriptions to just about anything in your schema to improve your developer experience |
Working with generic types
[CHILDREN asList]
[alert] You are viewing docs for a pre-release version of silverstripe/graphql (4.x). Help us improve it by joining #graphql on the Community Slack, and report any issues at github.com/silverstripe/silverstripe-graphql. Docs for the current stable version (3.x) can be found here [/alert]
Adding descriptions
One of the great features of a schema-backed API is that it is self-documenting. 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]