Merge branch 'ld-graphql-docs-enum' into 'master'

Include enum types in auto-generated GraphQL docs

See merge request gitlab-org/gitlab!41840

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

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)
+    \

spec/lib/gitlab/graphql/docs/renderer_spec.rb

@@ -36,10 +36,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
 
       specify do
         expectation = <<~DOC
-          ## ArrayTest
+          ### ArrayTest
 
-          | Name  | Type  | Description |
-          | ---   |  ---- | ----------  |
+          | Field | Type | Description |
+          | ----- | ---- | ----------- |
           | `foo` | String! => Array | A description |
         DOC
 
@@ -59,10 +59,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
 
       specify do
         expectation = <<~DOC
-          ## OrderingTest
+          ### OrderingTest
 
-          | Name  | Type  | Description |
-          | ---   |  ---- | ----------  |
+          | Field | Type | Description |
+          | ----- | ---- | ----------- |
           | `bar` | String! | A description of bar field |
           | `foo` | String! | A description of foo field |
         DOC
@@ -82,15 +82,45 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
 
       specify do
         expectation = <<~DOC
-          ## DeprecatedTest
+          ### DeprecatedTest
 
-          | Name  | Type  | Description |
-          | ---   |  ---- | ----------  |
+          | Field | Type | Description |
+          | ----- | ---- | ----------- |
           | `foo` **{warning-solid}** | String! | **Deprecated:** This is deprecated. Deprecated in 1.10 |
         DOC
 
         is_expected.to include(expectation)
       end
     end
+
+    context 'A type with an emum field' do
+      let(:type) do
+        enum_type = Class.new(Types::BaseEnum) do
+          graphql_name 'MyEnum'
+
+          value 'BAZ', description: 'A description of BAZ'
+          value 'BAR', description: 'A description of BAR', deprecation_reason: 'This is deprecated'
+        end
+
+        Class.new(Types::BaseObject) do
+          graphql_name 'EnumTest'
+
+          field :foo, enum_type, null: false, description: 'A description of foo field'
+        end
+      end
+
+      specify do
+        expectation = <<~DOC
+          ### MyEnum
+
+          | Value | Description |
+          | ----- | ----------- |
+          | `BAR` **{warning-solid}** | **Deprecated:** This is deprecated |
+          | `BAZ` | A description of BAZ |
+        DOC
+
+        is_expected.to include(expectation)
+      end
+    end
   end
 end