Add latest changes from gitlab-org/gitlab@master

2 files changed, 7 insertions, 3 deletions

diff --git a/lib/gitlab/graphql/docs/renderer.rb b/lib/gitlab/graphql/docs/renderer.rb
index 41aef64f683..6abd56c89c6 100644
--- a/lib/gitlab/graphql/docs/renderer.rb
+++ b/lib/gitlab/graphql/docs/renderer.rb
@@ -10,7 +10,7 @@ module Gitlab
       # It uses graphql-docs helpers and schema parser, more information in https://github.com/gjtorikian/graphql-docs.
       #
       # Arguments:
-      #   schema - the GraphQL schema defition. For GitLab should be: GitlabSchema.graphql_definition
+      #   schema - the GraphQL schema definition. For GitLab should be: GitlabSchema.graphql_definition
       #   output_dir: The folder where the markdown files will be saved
       #   template: The path of the haml template to be parsed
       class Renderer
diff --git a/lib/gitlab/graphql/docs/templates/default.md.haml b/lib/gitlab/graphql/docs/templates/default.md.haml
index 33acff38ef4..52568286dca 100644
--- a/lib/gitlab/graphql/docs/templates/default.md.haml
+++ b/lib/gitlab/graphql/docs/templates/default.md.haml
@@ -9,11 +9,15 @@
 
   The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
 
-  ## Objects
+Each table below documents a GraphQL type. Types match loosely to models, but not all
+fields and methods on a model are available via GraphQL.
 \
 - objects.each do |type|
   - unless type[:fields].empty?
-    = "### #{type[:name]}"
+    = "## #{type[:name]}"
+    - if type[:description]&.present?
+      \
+      = type[:description]
     \
     ~ "| Name  | Type  | Description |"
     ~ "| ---   |  ---- | ----------  |"