Commit 4bda06f8 authored by Luke Duncalfe's avatar Luke Duncalfe

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
parent ea41f945
...@@ -13,6 +13,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph ...@@ -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 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. fields and methods on a model are available via GraphQL.
CAUTION: **Caution:**
Fields that are deprecated are marked with **{warning-solid}**.
## AddAwardEmojiPayload ## AddAwardEmojiPayload
Autogenerated return type of AddAwardEmoji Autogenerated return type of AddAwardEmoji
...@@ -69,7 +72,7 @@ Represents a project or group board ...@@ -69,7 +72,7 @@ Represents a project or group board
| `authoredDate` | Time | Timestamp of when the commit was authored | | `authoredDate` | Time | Timestamp of when the commit was authored |
| `description` | String | Description of the commit message | | `description` | String | Description of the commit message |
| `id` | ID! | ID (global ID) of the commit | | `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 | | `message` | String | Raw commit message |
| `sha` | String! | SHA1 ID of the commit | | `sha` | String! | SHA1 ID of the commit |
| `signatureHtml` | String | Rendered HTML of the commit signature | | `signatureHtml` | String | Rendered HTML of the commit signature |
...@@ -347,7 +350,7 @@ Relationship between an epic and an issue ...@@ -347,7 +350,7 @@ Relationship between an epic and an issue
| `description` | String | Description of the issue | | `description` | String | Description of the issue |
| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
| `designCollection` | DesignCollection | Collection of design images associated with this issue | | `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 | | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue |
| `downvotes` | Int! | Number of downvotes the issue has received | | `downvotes` | Int! | Number of downvotes the issue has received |
| `dueDate` | Time | Due date of the issue | | `dueDate` | Time | Due date of the issue |
...@@ -417,7 +420,7 @@ Autogenerated return type of EpicTreeReorder ...@@ -417,7 +420,7 @@ Autogenerated return type of EpicTreeReorder
| `enabled` | Boolean! | Indicates whether Grafana integration is enabled | | `enabled` | Boolean! | Indicates whether Grafana integration is enabled |
| `grafanaUrl` | String! | Url for the Grafana host for the Grafana integration | | `grafanaUrl` | String! | Url for the Grafana host for the Grafana integration |
| `id` | ID! | Internal ID of 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 | | `updatedAt` | Time! | Timestamp of the issue's last activity |
## Group ## Group
...@@ -469,7 +472,7 @@ Autogenerated return type of EpicTreeReorder ...@@ -469,7 +472,7 @@ Autogenerated return type of EpicTreeReorder
| `description` | String | Description of the issue | | `description` | String | Description of the issue |
| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
| `designCollection` | DesignCollection | Collection of design images associated with this issue | | `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 | | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue |
| `downvotes` | Int! | Number of downvotes the issue has received | | `downvotes` | Int! | Number of downvotes the issue has received |
| `dueDate` | Time | Due date of the issue | | `dueDate` | Time | Due date of the issue |
...@@ -578,7 +581,7 @@ Autogenerated return type of MarkAsSpamSnippet ...@@ -578,7 +581,7 @@ Autogenerated return type of MarkAsSpamSnippet
| `id` | ID! | ID of the merge request | | `id` | ID! | ID of the merge request |
| `iid` | String! | Internal 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 | | `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) | | `mergeCommitSha` | String | SHA of the merge request commit (set once merged) |
| `mergeError` | String | Error message due to a merge error | | `mergeError` | String | Error message due to a merge error |
| `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring | | `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring |
......
...@@ -25,6 +25,28 @@ module Gitlab ...@@ -25,6 +25,28 @@ module Gitlab
fields.sort_by { |field| field[:name] } fields.sort_by { |field| field[:name] }
end 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 # Some fields types are arrays of other types and are displayed
# on docs wrapped in square brackets, for example: [String!]. # on docs wrapped in square brackets, for example: [String!].
# This makes GitLab docs renderer thinks they are links so here # This makes GitLab docs renderer thinks they are links so here
......
...@@ -11,6 +11,9 @@ ...@@ -11,6 +11,9 @@
Each table below documents a GraphQL type. Types match loosely to models, but not all 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. 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| - objects.each do |type|
- unless type[:fields].empty? - unless type[:fields].empty?
...@@ -22,5 +25,5 @@ ...@@ -22,5 +25,5 @@
~ "| Name | Type | Description |" ~ "| Name | Type | Description |"
~ "| --- | ---- | ---------- |" ~ "| --- | ---- | ---------- |"
- sorted_fields(type[:fields]).each do |field| - sorted_fields(type[:fields]).each do |field|
= "| `#{field[:name]}` | #{render_field_type(field[:type][:info])} | #{field[:description]} |" = render_field(field)
\ \
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment