From 435b3fa9cb76809f8798bb96a6127b8e19717f01 Mon Sep 17 00:00:00 2001 From: Luke Duncalfe Date: Thu, 5 Sep 2019 10:28:51 +1200 Subject: Document our GraphQL Enum standards https://gitlab.com/gitlab-org/gitlab-ce/issues/67012 --- doc/development/api_graphql_styleguide.md | 38 +++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 7569ccc04c1..ce0b29b1eab 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -191,6 +191,44 @@ end policies at once. The fields for these will all have be non-nullable booleans with a default description. +## Enums + +GraphQL Enums are defined in `app/graphql/types`. Our GitLab styleguide standards for Enums are: + +- The values must be uppercase +- The class name must end in `Enum` +- The `graphql_name` must not have `Enum` in it + +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 Rails that is not an uppercase string, then 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'` and 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 -- cgit v1.2.1