Add deprecation reason to GraphQL API docs

Where a field has been deprecated in the GraphQL schema, the deprecation
reason now replaces the description.

https://gitlab.com/gitlab-org/gitlab/issues/198571

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