2 files changed, 73 insertions, 19 deletions

diff --git a/lib/gitlab/graphql/docs/helper.rb b/lib/gitlab/graphql/docs/helper.rb
index 0dd28b32511..dcd0e12cbfc 100644
--- a/lib/gitlab/graphql/docs/helper.rb
+++ b/lib/gitlab/graphql/docs/helper.rb
@@ -21,30 +21,47 @@ module Gitlab
           MD
         end
 
-        def sorted_fields(fields)
-          fields.sort_by { |field| field[:name] }
+        def render_name_and_description(object)
+          content = "### #{object[:name]}\n"
+
+          if object[:description].present?
+            content += "\n#{object[:description]}.\n"
+          end
+
+          content
+        end
+
+        def sorted_by_name(objects)
+          objects.sort_by { |o| o[:name] }
         end
 
         def render_field(field)
           '| %s | %s | %s |' % [
-            render_field_name(field),
+            render_name(field),
             render_field_type(field[:type][:info]),
-            render_field_description(field)
+            render_description(field)
             ]
         end
 
-        def render_field_name(field)
-          rendered_name = "`#{field[:name]}`"
-          rendered_name += ' **{warning-solid}**' if field[:is_deprecated]
+        def render_enum_value(value)
+          '| %s | %s |' % [
+            render_name(value),
+            render_description(value)
+            ]
+        end
+
+        def render_name(object)
+          rendered_name = "`#{object[:name]}`"
+          rendered_name += ' **{warning-solid}**' if object[:is_deprecated]
           rendered_name
         end
 
-        # Returns the field description. If the field has been deprecated,
+        # Returns the object description. If the object has been deprecated,
         # the deprecation reason will be returned in place of the description.
-        def render_field_description(field)
-          return field[:description] unless field[:is_deprecated]
+        def render_description(object)
+          return object[:description] unless object[:is_deprecated]
 
-          "**Deprecated:** #{field[:deprecation_reason]}"
+          "**Deprecated:** #{object[:deprecation_reason]}"
         end
 
         # Some fields types are arrays of other types and are displayed
@@ -70,6 +87,13 @@ module Gitlab
               !object_type[:name]["__"]
           end
         end
+
+        # We ignore the built-in enum types.
+        def enums
+          graphql_enum_types.select do |enum_type|
+            !enum_type[:name].in?(%w(__DirectiveLocation __TypeKind))
+          end
+        end
       end
     end
   end
diff --git a/lib/gitlab/graphql/docs/templates/default.md.haml b/lib/gitlab/graphql/docs/templates/default.md.haml
index 8c033526557..ec052943589 100644
--- a/lib/gitlab/graphql/docs/templates/default.md.haml
+++ b/lib/gitlab/graphql/docs/templates/default.md.haml
@@ -15,15 +15,45 @@
   CAUTION: **Caution:**
   Fields that are deprecated are marked with **{warning-solid}**.
 \
+
+:plain
+  ## Object types
+
+  Object types represent the resources that GitLab's GraphQL API can return.
+  They contain _fields_. Each field has its own type, which will either be one of the
+  basic GraphQL [scalar types](https://graphql.org/learn/schema/#scalar-types)
+  (e.g.: `String` or `Boolean`) or other object types.
+
+  For more information, see
+  [Object Types and Fields](https://graphql.org/learn/schema/#object-types-and-fields)
+  on `graphql.org`.
+\
+
 - objects.each do |type|
   - unless type[:fields].empty?
-    = "## #{type[:name]}"
-    - if type[:description]&.present?
-      \
-      = type[:description]
-    \
-    ~ "| Name  | Type  | Description |"
-    ~ "| ---   |  ---- | ----------  |"
-    - sorted_fields(type[:fields]).each do |field|
+    = render_name_and_description(type)
+    ~ "| Field | Type | Description |"
+    ~ "| ----- | ---- | ----------- |"
+    - sorted_by_name(type[:fields]).each do |field|
       = render_field(field)
     \
+
+:plain
+  ## Enumeration types
+
+  Also called _Enums_, enumeration types are a special kind of scalar that
+  is restricted to a particular set of allowed values.
+
+  For more information, see
+  [Enumeration Types](https://graphql.org/learn/schema/#enumeration-types)
+  on `graphql.org`.
+\
+
+- enums.each do |enum|
+  - unless enum[:values].empty?
+    = render_name_and_description(enum)
+    ~ "| Value | Description |"
+    ~ "| ----- | ----------- |"
+    - sorted_by_name(enum[:values]).each do |value|
+      = render_enum_value(value)
+    \