Merge branch '198571-graphql-api-docs-show-deprecated-fields' into 'master'

Add deprecation reason to GraphQL API docs

See merge request gitlab-org/gitlab!24331

doc/api/graphql/reference/index.md

@@ -13,6 +13,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 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.
 
+CAUTION: **Caution:**
+Fields that are deprecated are marked with **{warning-solid}**.
+
 ## AddAwardEmojiPayload
 
 Autogenerated return type of AddAwardEmoji
@@ -69,7 +72,7 @@ Represents a project or group board
 | `authoredDate` | Time | Timestamp of when the commit was authored |
 | `description` | String | Description of the commit message |
 | `id` | ID! | ID (global ID) of the commit |
-| `latestPipeline` | Pipeline | Latest pipeline of the commit |
+| `latestPipeline` **{warning-solid}** | Pipeline | **Deprecated:** Use pipelines |
 | `message` | String | Raw commit message |
 | `sha` | String! | SHA1 ID of the commit |
 | `signatureHtml` | String | Rendered HTML of the commit signature |
@@ -347,7 +350,7 @@ Relationship between an epic and an issue
 | `description` | String | Description of the issue |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `designCollection` | DesignCollection | Collection of design images associated with this issue |
-| `designs` | DesignCollection | Deprecated. Use `designCollection` |
+| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use designCollection |
 | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue |
 | `downvotes` | Int! | Number of downvotes the issue has received |
 | `dueDate` | Time | Due date of the issue |
@@ -417,7 +420,7 @@ Autogenerated return type of EpicTreeReorder
 | `enabled` | Boolean! | Indicates whether Grafana integration is enabled |
 | `grafanaUrl` | String! | Url for the Grafana host for the Grafana integration |
 | `id` | ID! | Internal ID of the Grafana integration |
-| `token` | String! | API token for the Grafana integration. Field is permanently masked. |
+| `token` **{warning-solid}** | String! | **Deprecated:** Plain text token has been masked for security reasons |
 | `updatedAt` | Time! | Timestamp of the issue's last activity |
 
 ## Group
@@ -469,7 +472,7 @@ Autogenerated return type of EpicTreeReorder
 | `description` | String | Description of the issue |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `designCollection` | DesignCollection | Collection of design images associated with this issue |
-| `designs` | DesignCollection | Deprecated. Use `designCollection` |
+| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use designCollection |
 | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue |
 | `downvotes` | Int! | Number of downvotes the issue has received |
 | `dueDate` | Time | Due date of the issue |
@@ -578,7 +581,7 @@ Autogenerated return type of MarkAsSpamSnippet
 | `id` | ID! | ID of the merge request |
 | `iid` | String! | Internal ID of the merge request |
 | `inProgressMergeCommitSha` | String | Commit SHA of the merge request if merge is in progress |
-| `mergeCommitMessage` | String | Deprecated - renamed to defaultMergeCommitMessage |
+| `mergeCommitMessage` **{warning-solid}** | String | **Deprecated:** Renamed to defaultMergeCommitMessage |
 | `mergeCommitSha` | String | SHA of the merge request commit (set once merged) |
 | `mergeError` | String | Error message due to a merge error |
 | `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring |

lib/gitlab/graphql/docs/helper.rb

@@ -25,6 +25,28 @@ module Gitlab
           fields.sort_by { |field| field[:name] }
         end
 
+        def render_field(field)
+          '| %s | %s | %s |' % [
+            render_field_name(field),
+            render_field_type(field[:type][:info]),
+            render_field_description(field)
+            ]
+        end
+
+        def render_field_name(field)
+          rendered_name = "`#{field[:name]}`"
+          rendered_name += ' **{warning-solid}**' if field[:is_deprecated]
+          rendered_name
+        end
+
+        # Returns the field description. If the field 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]
+
+          "**Deprecated:** #{field[:deprecation_reason]}"
+        end
+
         # Some fields types are arrays of other types and are displayed
         # on docs wrapped in square brackets, for example: [String!].
         # This makes GitLab docs renderer thinks they are links so here

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -11,6 +11,9 @@
 
   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.
+
+  CAUTION: **Caution:**
+  Fields that are deprecated are marked with **{warning-solid}**.
 \
 - objects.each do |type|
   - unless type[:fields].empty?
@@ -22,5 +25,5 @@
     ~ "| Name  | Type  | Description |"
     ~ "| ---   |  ---- | ----------  |"
     - sorted_fields(type[:fields]).each do |field|
-      = "| `#{field[:name]}` | #{render_field_type(field[:type][:info])} | #{field[:description]} |"
+      = render_field(field)
     \

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

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Gitlab::Graphql::Docs::Renderer do
+  describe '#contents' do
+    # Returns a Schema that uses the given `type`
+    def mock_schema(type)
+      query_type = Class.new(GraphQL::Schema::Object) do
+        graphql_name 'QueryType'
+
+        field :foo, type, null: true
+      end
+
+      GraphQL::Schema.define(query: query_type)
+    end
+
+    let_it_be(:template) { Rails.root.join('lib/gitlab/graphql/docs/templates/', 'default.md.haml') }
+
+    subject(:contents) do
+      described_class.new(
+        mock_schema(type).graphql_definition,
+        output_dir: nil,
+        template: template
+      ).contents
+    end
+
+    context 'A type with a field with a [Array] return type' do
+      let(:type) do
+        Class.new(GraphQL::Schema::Object) do
+          graphql_name 'ArrayTest'
+
+          field :foo, [GraphQL::STRING_TYPE], null: false, description: 'A description'
+        end
+      end
+
+      specify do
+        expectation = <<~DOC
+          ## ArrayTest
+
+          | Name  | Type  | Description |
+          | ---   |  ---- | ----------  |
+          | `foo` | String! => Array | A description |
+        DOC
+
+        is_expected.to include(expectation)
+      end
+    end
+
+    context 'A type with fields defined in reverse alphabetical order' do
+      let(:type) do
+        Class.new(GraphQL::Schema::Object) do
+          graphql_name 'OrderingTest'
+
+          field :foo, GraphQL::STRING_TYPE, null: false, description: 'A description of foo field'
+          field :bar, GraphQL::STRING_TYPE, null: false, description: 'A description of bar field'
+        end
+      end
+
+      specify do
+        expectation = <<~DOC
+          ## OrderingTest
+
+          | Name  | Type  | Description |
+          | ---   |  ---- | ----------  |
+          | `bar` | String! | A description of bar field |
+          | `foo` | String! | A description of foo field |
+        DOC
+
+        is_expected.to include(expectation)
+      end
+    end
+
+    context 'A type with a deprecated field' do
+      let(:type) do
+        Class.new(GraphQL::Schema::Object) do
+          graphql_name 'DeprecatedTest'
+
+          field :foo, GraphQL::STRING_TYPE, null: false, deprecation_reason: 'This is deprecated', description: 'A description'
+        end
+      end
+
+      specify do
+        expectation = <<~DOC
+          ## DeprecatedTest
+
+          | Name  | Type  | Description |
+          | ---   |  ---- | ----------  |
+          | `foo` **{warning-solid}** | String! | **Deprecated:** This is deprecated |
+        DOC
+
+        is_expected.to include(expectation)
+      end
+    end
+  end
+end