Document our GraphQL Enum standardsdocs-graphql-enums

https://gitlab.com/gitlab-org/gitlab-ce/issues/67012

1 files changed, 38 insertions, 0 deletions

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