Merge branch 'docs-cablett-graphql-headings' into 'master'

Show Graphql type descriptions

See merge request gitlab-org/gitlab!22568

app/graphql/types/award_emojis/award_emoji_type.rb

@@ -4,6 +4,7 @@ module Types
   module AwardEmojis
     class AwardEmojiType < BaseObject
       graphql_name 'AwardEmoji'
+      description 'An emoji awarded by a user.'
 
       authorize :read_emoji
 

doc/api/graphql/reference/gitlab_schema.graphql

@@ -38,6 +38,9 @@ type AddAwardEmojiPayload {
   errors: [String!]!
 }
 
+"""
+An emoji awarded by a user.
+"""
 type AwardEmoji {
   """
   The emoji description
@@ -529,6 +532,9 @@ type CreateSnippetPayload {
   snippet: Snippet
 }
 
+"""
+A single design
+"""
 type Design implements DesignFields & Noteable {
   """
   The diff refs for this design
@@ -651,6 +657,9 @@ type Design implements DesignFields & Noteable {
   ): DesignVersionConnection!
 }
 
+"""
+A collection of designs.
+"""
 type DesignCollection {
   """
   All designs for the design collection
@@ -979,7 +988,7 @@ type DesignVersionEdge {
 }
 
 """
-Mutation event of a Design within a Version
+Mutation event of a design within a version
 """
 enum DesignVersionEvent {
   """
@@ -1403,6 +1412,9 @@ enum EntryType {
   tree
 }
 
+"""
+Represents an epic.
+"""
 type Epic implements Noteable {
   """
   Author of the epic
@@ -1761,6 +1773,9 @@ type EpicConnection {
   pageInfo: PageInfo!
 }
 
+"""
+Counts of descendent epics.
+"""
 type EpicDescendantCount {
   """
   Number of closed sub-epics
@@ -1798,6 +1813,9 @@ type EpicEdge {
   node: Epic
 }
 
+"""
+Relationship between an epic and an issue
+"""
 type EpicIssue implements Noteable {
   """
   Assignees of the issue
@@ -2246,7 +2264,7 @@ enum EpicSort {
 }
 
 """
-State of a GitLab epic
+State of an epic.
 """
 enum EpicState {
   all
@@ -2255,20 +2273,23 @@ enum EpicState {
 }
 
 """
-State event of a GitLab Epic
+State event of an epic
 """
 enum EpicStateEvent {
   """
-  Close the Epic
+  Close the epic
   """
   CLOSE
 
   """
-  Reopen the Epic
+  Reopen the epic
   """
   REOPEN
 }
 
+"""
+A node of an epic tree.
+"""
 input EpicTreeNodeFieldsInputType {
   """
   The id of the epic_issue or issue that the actual epic or issue is switched with

doc/api/graphql/reference/gitlab_schema.json

@@ -3695,7 +3695,7 @@
         {
           "kind": "OBJECT",
           "name": "Epic",
-          "description": null,
+          "description": "Represents an epic.",
           "fields": [
             {
               "name": "author",
@@ -7384,7 +7384,7 @@
         {
           "kind": "ENUM",
           "name": "EpicState",
-          "description": "State of a GitLab epic",
+          "description": "State of an epic.",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -8009,7 +8009,7 @@
         {
           "kind": "OBJECT",
           "name": "EpicIssue",
-          "description": null,
+          "description": "Relationship between an epic and an issue",
           "fields": [
             {
               "name": "assignees",
@@ -9230,7 +9230,7 @@
         {
           "kind": "OBJECT",
           "name": "DesignCollection",
-          "description": null,
+          "description": "A collection of designs.",
           "fields": [
             {
               "name": "designs",
@@ -10346,7 +10346,7 @@
         {
           "kind": "OBJECT",
           "name": "Design",
-          "description": null,
+          "description": "A single design",
           "fields": [
             {
               "name": "diffRefs",
@@ -10880,7 +10880,7 @@
         {
           "kind": "ENUM",
           "name": "DesignVersionEvent",
-          "description": "Mutation event of a Design within a Version",
+          "description": "Mutation event of a design within a version",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -11133,7 +11133,7 @@
         {
           "kind": "OBJECT",
           "name": "EpicDescendantCount",
-          "description": null,
+          "description": "Counts of descendent epics.",
           "fields": [
             {
               "name": "closedEpics",
@@ -16943,7 +16943,7 @@
         {
           "kind": "OBJECT",
           "name": "AwardEmoji",
-          "description": null,
+          "description": "An emoji awarded by a user.",
           "fields": [
             {
               "name": "description",
@@ -20689,7 +20689,7 @@
         {
           "kind": "INPUT_OBJECT",
           "name": "EpicTreeNodeFieldsInputType",
-          "description": null,
+          "description": "A node of an epic tree.",
           "fields": null,
           "inputFields": [
             {
@@ -20987,20 +20987,20 @@
         {
           "kind": "ENUM",
           "name": "EpicStateEvent",
-          "description": "State event of a GitLab Epic",
+          "description": "State event of an epic",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
           "enumValues": [
             {
               "name": "REOPEN",
-              "description": "Reopen the Epic",
+              "description": "Reopen the epic",
               "isDeprecated": false,
               "deprecationReason": null
             },
             {
               "name": "CLOSE",
-              "description": "Close the Epic",
+              "description": "Close the epic",
               "isDeprecated": false,
               "deprecationReason": null
             }

ee/app/graphql/types/design_management/design_collection_type.rb

@@ -4,6 +4,7 @@ module Types
   module DesignManagement
     class DesignCollectionType < BaseObject
       graphql_name 'DesignCollection'
+      description 'A collection of designs.'
 
       authorize :read_design
 

ee/app/graphql/types/design_management/design_type.rb

@@ -4,6 +4,7 @@ module Types
   module DesignManagement
     class DesignType < BaseObject
       graphql_name 'Design'
+      description 'A single design'
 
       authorize :read_design
 

ee/app/graphql/types/design_management/design_version_event_enum.rb

@@ -4,7 +4,7 @@ module Types
   module DesignManagement
     class DesignVersionEventEnum < BaseEnum
       graphql_name 'DesignVersionEvent'
-      description 'Mutation event of a Design within a Version'
+      description 'Mutation event of a design within a version'
 
       NONE = 'NONE'
 

ee/app/graphql/types/epic_descendant_count_type.rb

@@ -4,6 +4,7 @@ module Types
   # rubocop: disable Graphql/AuthorizeTypes
   class EpicDescendantCountType < BaseObject
     graphql_name 'EpicDescendantCount'
+    description 'Counts of descendent epics.'
 
     field :opened_epics, GraphQL::INT_TYPE, null: true, description: 'Number of opened sub-epics'
     field :closed_epics, GraphQL::INT_TYPE, null: true, description: 'Number of closed sub-epics'

ee/app/graphql/types/epic_issue_type.rb

@@ -5,6 +5,7 @@ module Types
   # This is a subclass of `IssueType` which has authorization
   class EpicIssueType < IssueType
     graphql_name 'EpicIssue'
+    description 'Relationship between an epic and an issue'
 
     present_using EpicIssuePresenter
 

ee/app/graphql/types/epic_state_enum.rb

@@ -3,7 +3,7 @@
 module Types
   class EpicStateEnum < BaseEnum
     graphql_name 'EpicState'
-    description 'State of a GitLab epic'
+    description 'State of an epic.'
 
     value 'all'
     value 'opened'

ee/app/graphql/types/epic_state_event_enum.rb

@@ -3,9 +3,9 @@
 module Types
   class EpicStateEventEnum < BaseEnum
     graphql_name 'EpicStateEvent'
-    description 'State event of a GitLab Epic'
+    description 'State event of an epic'
 
-    value 'REOPEN', value: 'reopen', description: 'Reopen the Epic'
-    value 'CLOSE', value: 'close', description: 'Close the Epic'
+    value 'REOPEN', value: 'reopen', description: 'Reopen the epic'
+    value 'CLOSE', value: 'close', description: 'Close the epic'
   end
 end

ee/app/graphql/types/epic_tree/epic_tree_node_input_type.rb

@@ -5,6 +5,7 @@ module Types
     # rubocop: disable Graphql/AuthorizeTypes
     class EpicTreeNodeInputType < BaseInputObject
       graphql_name 'EpicTreeNodeFieldsInputType'
+      description 'A node of an epic tree.'
 
       MoveTypeEnum = GraphQL::EnumType.define do
         name 'MoveType'

ee/app/graphql/types/epic_type.rb

@@ -3,6 +3,7 @@
 module Types
   class EpicType < BaseObject
     graphql_name 'Epic'
+    description 'Represents an epic.'
 
     authorize :read_epic
 

ee/app/graphql/types/permission_types/epic.rb

@@ -3,8 +3,8 @@
 module Types
   module PermissionTypes
     class Epic < BasePermissionType
-      description 'Check permissions for the current user on an epic'
       graphql_name 'EpicPermissions'
+      description 'Check permissions for the current user on an epic'
 
       abilities :read_epic, :read_epic_iid, :update_epic, :destroy_epic, :admin_epic,
                 :create_epic, :create_note, :award_emoji

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

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 |"
     ~ "| ---   |  ---- | ----------  |"