diff options
author | Evan Read <eread@gitlab.com> | 2019-09-06 03:54:51 +0000 |
---|---|---|
committer | Evan Read <eread@gitlab.com> | 2019-09-06 03:54:51 +0000 |
commit | 13227500f29d8a74c77cba23b7dfdb4169222821 (patch) | |
tree | 32326de09418e404ac74b2b05398bd5449ba8b6c | |
parent | 7fd27257c451cf8e3c4456adcaa457369d087b8f (diff) | |
parent | a7400984147f25c6fa8dbfd8f39bdc1507423840 (diff) | |
download | gitlab-ce-13227500f29d8a74c77cba23b7dfdb4169222821.tar.gz |
Merge branch 'docs-graphql-enums' into 'master'
Document our GraphQL Enum standards
See merge request gitlab-org/gitlab-ce!32678
-rw-r--r-- | doc/development/api_graphql_styleguide.md | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 7569ccc04c1..c3165dc2e21 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -191,6 +191,51 @@ end policies at once. The fields for these will all have be non-nullable booleans with a default description. +## Enums + +GitLab GraphQL enums are defined in `app/graphql/types`. When defining new enums, the +following rules apply: + +- Values must be uppercase. +- Class names must end with the string `Enum`. +- The `graphql_name` must not contain the string `Enum`. + +For example: + +```ruby +module Types + class TrafficLightStateEnum < BaseEnum + graphql_name 'TrafficLightState' + description 'State of a traffic light' + + value 'RED', description: 'Drivers must stop' + value 'YELLOW', description: 'Drivers must stop when it is safe to' + value 'GREEN', description: 'Drivers can start or keep driving' + end +end +``` + +If the enum will be used for a class property in Ruby that is not an uppercase string, +you can provide a `value:` option that will adapt the uppercase value. + +In the following example: + +- GraphQL inputs of `OPENED` will be converted to `'opened'`. +- Ruby values of `'opened'` will be converted to `"OPENED"` in GraphQL responses. + +```ruby +module Types + class EpicStateEnum < BaseEnum + graphql_name 'EpicState' + description 'State of a GitLab epic' + + value 'OPENED', value: 'opened', description: 'An open Epic' + value 'CLOSED', value: 'closed', description: 'An closed Epic' + end +end + +``` + ## Authorization Authorizations can be applied to both types and fields using the same |