Skip to content

G
gitlab-ce
Commit dd534ff4 authored by Mike Jang's avatar Mike Jang
Browse files
Options

Merge branch 'ld-docs-query-type-fixes' into 'master' 

GraphQL API reference docs: Query type fixes

See merge request gitlab-org/gitlab!55336
parents 9b284083 7a74ba12
Hide whitespace changes
Inline Side-by-side
Showing with 235 additions and 197 deletions
doc/api/graphql/reference/index.md
View file @ dd534ff4
...@@ -26,293 +26,339 @@ in [Removed Items](../removed_items.md). ...@@ -26,293 +26,339 @@ in [Removed Items](../removed_items.md).
<!-- vale gitlab.Spelling = NO --> <!-- vale gitlab.Spelling = NO -->
## Queries ## `Query` type
Queries are used to get the resources, filter or query them. The `Query` type contains the API's top-level entry points for all executable queries.
For more information, visit [Queries and Mutations](https://graphql.org/learn/queries/). ### ciApplicationSettings
### CiApplicationSettings
CI related settings that apply to the entire instance. CI related settings that apply to the entire instance.
### CiConfig ### ciConfig
Get linted and processed contents of a CI config. Should not be requested more than once per request. Get linted and processed contents of a CI config. Should not be requested more than once per request.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `content` | Contents of `.gitlab-ci.yml`. | String! |
| `dryRun` | Run pipeline creation simulation, or only do static check. | Boolean |
| `projectPath` | The project of the CI config. | ID! |
### ContainerRepository | Name | Type | Description |
| ---- | ---- | ----------- |
| `content` | String! | Contents of `.gitlab-ci.yml`. |
| `dryRun` | Boolean | Run pipeline creation simulation, or only do static check. |
| `projectPath` | ID! | The project of the CI config. |
### containerRepository
Find a container repository. Find a container repository.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | The global ID of the container repository. | ContainerRepositoryID! |
### CurrentUser | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | ContainerRepositoryID! | The global ID of the container repository. |
### currentUser
Get information about current user. Get information about current user.
### DesignManagement ### designManagement
Fields related to design management. Fields related to design management.
### DevopsAdoptionSegments ### devopsAdoptionSegments
Get configured DevOps adoption segments on the instance. Get configured DevOps adoption segments on the instance.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String | | Name | Type | Description |
| `before` | Returns the elements in the list that come before the specified cursor. | String | | ---- | ---- | ----------- |
| `first` | Returns the first _n_ elements from the list. | Int | | `after` | String | Returns the elements in the list that come after the specified cursor. |
| `last` | Returns the last _n_ elements from the list. | Int | | `before` | String | Returns the elements in the list that come before the specified cursor. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `last` | Int | Returns the last _n_ elements from the list. |
### Echo ### echo
Text to echo back. Text to echo back.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `text` | Text to echo back. | String! |
### GeoNode | Name | Type | Description |
| ---- | ---- | ----------- |
| `text` | String! | Text to echo back. |
### geoNode
Find a Geo node. Find a Geo node.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `name` | The name of the Geo node. Defaults to the current Geo node name. | String |
### Group | Name | Type | Description |
| ---- | ---- | ----------- |
| `name` | String | The name of the Geo node. Defaults to the current Geo node name. |
### group
Find a group. Find a group.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `fullPath` | The full path of the project, group or namespace, e.g., `gitlab-org/gitlab-foss`. | ID! |
### InstanceSecurityDashboard | Name | Type | Description |
| ---- | ---- | ----------- |
| `fullPath` | ID! | The full path of the project, group or namespace, e.g., `gitlab-org/gitlab-foss`. |
### instanceSecurityDashboard
Fields related to Instance Security Dashboard. Fields related to Instance Security Dashboard.
### InstanceStatisticsMeasurements ### instanceStatisticsMeasurements
Get statistics on the instance. Deprecated in 13.10: This field was renamed. Use the `usageTrendsMeasurements` field instead. Get statistics on the instance. Deprecated in 13.10: This field was renamed. Use the `usageTrendsMeasurements` field instead.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `first` | Returns the first _n_ elements from the list. | Int |
| `identifier` | The type of measurement/statistics to retrieve. | MeasurementIdentifier! |
| `last` | Returns the last _n_ elements from the list. | Int |
| `recordedAfter` | Measurement recorded after this date. | Time |
| `recordedBefore` | Measurement recorded before this date. | Time |
### Issue | Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `identifier` | MeasurementIdentifier! | The type of measurement/statistics to retrieve. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `recordedAfter` | Time | Measurement recorded after this date. |
| `recordedBefore` | Time | Measurement recorded before this date. |
### issue
Find an Issue. Find an Issue.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | The global ID of the Issue. | IssueID! |
### Iteration | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | IssueID! | The global ID of the Issue. |
### iteration
Find an iteration. Find an iteration.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | Find an iteration by its ID. | IterationID! |
### Metadata | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | IterationID! | Find an iteration by its ID. |
### metadata
Metadata about GitLab. Metadata about GitLab.
### Milestone ### milestone
Find a milestone. Find a milestone.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | Find a milestone by its ID. | MilestoneID! |
### Namespace | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | MilestoneID! | Find a milestone by its ID. |
### namespace
Find a namespace. Find a namespace.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `fullPath` | The full path of the project, group or namespace, e.g., `gitlab-org/gitlab-foss`. | ID! |
### Package | Name | Type | Description |
| ---- | ---- | ----------- |
| `fullPath` | ID! | The full path of the project, group or namespace, e.g., `gitlab-org/gitlab-foss`. |
### package
Find a package. Find a package.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | The global ID of the package. | PackagesPackageID! |
### Project | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | PackagesPackageID! | The global ID of the package. |
### project
Find a project. Find a project.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `fullPath` | The full path of the project, group or namespace, e.g., `gitlab-org/gitlab-foss`. | ID! | | Name | Type | Description |
| ---- | ---- | ----------- |
| `fullPath` | ID! | The full path of the project, group or namespace, e.g., `gitlab-org/gitlab-foss`. |
### Projects ### projects
Find projects visible to the current user. Find projects visible to the current user.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String | | Name | Type | Description |
| `before` | Returns the elements in the list that come before the specified cursor. | String | | ---- | ---- | ----------- |
| `first` | Returns the first _n_ elements from the list. | Int | | `after` | String | Returns the elements in the list that come after the specified cursor. |
| `ids` | Filter projects by IDs. | ID! => Array | | `before` | String | Returns the elements in the list that come before the specified cursor. |
| `last` | Returns the last _n_ elements from the list. | Int | | `first` | Int | Returns the first _n_ elements from the list. |
| `membership` | Limit projects that the current user is a member of. | Boolean | | `ids` | ID! => Array | Filter projects by IDs. |
| `search` | Search query for project name, path, or description. | String | | `last` | Int | Returns the last _n_ elements from the list. |
| `searchNamespaces` | Include namespace in project search. | Boolean | | `membership` | Boolean | Limit projects that the current user is a member of. |
| `sort` | Sort order of results. | String | | `search` | String | Search query for project name, path, or description. |
| `searchNamespaces` | Boolean | Include namespace in project search. |
| `sort` | String | Sort order of results. |
### RunnerPlatforms ### runnerPlatforms
Supported runner platforms. Supported runner platforms.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `first` | Returns the first _n_ elements from the list. | Int |
| `last` | Returns the last _n_ elements from the list. | Int |
### RunnerSetup | Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `last` | Int | Returns the last _n_ elements from the list. |
### runnerSetup
Get runner setup instructions. Get runner setup instructions.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `architecture` | Architecture to generate the instructions for. | String! |
| `groupId` | Group to register the runner for. | GroupID |
| `platform` | Platform to generate the instructions for. | String! |
| `projectId` | Project to register the runner for. | ProjectID |
### Snippets | Name | Type | Description |
| ---- | ---- | ----------- |
| `architecture` | String! | Architecture to generate the instructions for. |
| `groupId` | GroupID | Group to register the runner for. |
| `platform` | String! | Platform to generate the instructions for. |
| `projectId` | ProjectID | Project to register the runner for. |
### snippets
Find Snippets visible to the current user. Find Snippets visible to the current user.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `authorId` | The ID of an author. | UserID |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `explore` | Explore personal snippets. | Boolean |
| `first` | Returns the first _n_ elements from the list. | Int |
| `ids` | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | SnippetID! => Array |
| `last` | Returns the last _n_ elements from the list. | Int |
| `projectId` | The ID of a project. | ProjectID |
| `type` | The type of snippet. | TypeEnum |
| `visibility` | The visibility of the snippet. | VisibilityScopesEnum |
### UsageTrendsMeasurements | Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `authorId` | UserID | The ID of an author. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `explore` | Boolean | Explore personal snippets. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `ids` | SnippetID! => Array | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `projectId` | ProjectID | The ID of a project. |
| `type` | TypeEnum | The type of snippet. |
| `visibility` | VisibilityScopesEnum | The visibility of the snippet. |
### usageTrendsMeasurements
Get statistics on the instance. Get statistics on the instance.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `first` | Returns the first _n_ elements from the list. | Int |
| `identifier` | The type of measurement/statistics to retrieve. | MeasurementIdentifier! |
| `last` | Returns the last _n_ elements from the list. | Int |
| `recordedAfter` | Measurement recorded after this date. | Time |
| `recordedBefore` | Measurement recorded before this date. | Time |
### User | Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `identifier` | MeasurementIdentifier! | The type of measurement/statistics to retrieve. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `recordedAfter` | Time | Measurement recorded after this date. |
| `recordedBefore` | Time | Measurement recorded before this date. |
### user
Find a user. Find a user.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | ID of the User. | UserID | | Name | Type | Description |
| `username` | Username of the User. | String | | ---- | ---- | ----------- |
| `id` | UserID | ID of the User. |
| `username` | String | Username of the User. |
### Users ### users
Find users. Find users.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `admins` | Return only admin users. | Boolean |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `first` | Returns the first _n_ elements from the list. | Int |
| `ids` | List of user Global IDs. | ID! => Array |
| `last` | Returns the last _n_ elements from the list. | Int |
| `search` | Query to search users by name, username, or primary email. | String |
| `sort` | Sort users by this criteria. | Sort |
| `usernames` | List of usernames. | String! => Array |
### Vulnerabilities | Name | Type | Description |
| ---- | ---- | ----------- |
| `admins` | Boolean | Return only admin users. |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `ids` | ID! => Array | List of user Global IDs. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `search` | String | Query to search users by name, username, or primary email. |
| `sort` | Sort | Sort users by this criteria. |
| `usernames` | String! => Array | List of usernames. |
Vulnerabilities reported on projects on the current user's instance security dashboard. ### vulnerabilities
| Name | Description | Type | Vulnerabilities reported on projects on the current user's instance security dashboard.
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `first` | Returns the first _n_ elements from the list. | Int |
| `hasIssues` | Returns only the vulnerabilities which have linked issues. | Boolean |
| `hasResolution` | Returns only the vulnerabilities which have been resolved on default branch. | Boolean |
| `last` | Returns the last _n_ elements from the list. | Int |
| `projectId` | Filter vulnerabilities by project. | ID! => Array |
| `reportType` | Filter vulnerabilities by report type. | VulnerabilityReportType! => Array |
| `scanner` | Filter vulnerabilities by VulnerabilityScanner.externalId. | String! => Array |
| `severity` | Filter vulnerabilities by severity. | VulnerabilitySeverity! => Array |
| `sort` | List vulnerabilities by sort order. | VulnerabilitySort |
| `state` | Filter vulnerabilities by state. | VulnerabilityState! => Array |
### VulnerabilitiesCountByDay #### Arguments
| Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `hasIssues` | Boolean | Returns only the vulnerabilities which have linked issues. |
| `hasResolution` | Boolean | Returns only the vulnerabilities which have been resolved on default branch. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `projectId` | ID! => Array | Filter vulnerabilities by project. |
| `reportType` | VulnerabilityReportType! => Array | Filter vulnerabilities by report type. |
| `scanner` | String! => Array | Filter vulnerabilities by VulnerabilityScanner.externalId. |
| `severity` | VulnerabilitySeverity! => Array | Filter vulnerabilities by severity. |
| `sort` | VulnerabilitySort | List vulnerabilities by sort order. |
| `state` | VulnerabilityState! => Array | Filter vulnerabilities by state. |
### vulnerabilitiesCountByDay
Number of vulnerabilities per day for the projects on the current user's instance security dashboard. Number of vulnerabilities per day for the projects on the current user's instance security dashboard.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `endDate` | Last day for which to fetch vulnerability history. | ISO8601Date! |
| `first` | Returns the first _n_ elements from the list. | Int |
| `last` | Returns the last _n_ elements from the list. | Int |
| `startDate` | First day for which to fetch vulnerability history. | ISO8601Date! |
### VulnerabilitiesCountByDayAndSeverity | Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `endDate` | ISO8601Date! | Last day for which to fetch vulnerability history. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `startDate` | ISO8601Date! | First day for which to fetch vulnerability history. |
### vulnerabilitiesCountByDayAndSeverity
Number of vulnerabilities per severity level, per day, for the projects on the current user's instance security dashboard. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`. Number of vulnerabilities per severity level, per day, for the projects on the current user's instance security dashboard. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `after` | Returns the elements in the list that come after the specified cursor. | String |
| `before` | Returns the elements in the list that come before the specified cursor. | String |
| `endDate` | Last day for which to fetch vulnerability history. | ISO8601Date! |
| `first` | Returns the first _n_ elements from the list. | Int |
| `last` | Returns the last _n_ elements from the list. | Int |
| `startDate` | First day for which to fetch vulnerability history. | ISO8601Date! |
### Vulnerability | Name | Type | Description |
| ---- | ---- | ----------- |
| `after` | String | Returns the elements in the list that come after the specified cursor. |
| `before` | String | Returns the elements in the list that come before the specified cursor. |
| `endDate` | ISO8601Date! | Last day for which to fetch vulnerability history. |
| `first` | Int | Returns the first _n_ elements from the list. |
| `last` | Int | Returns the last _n_ elements from the list. |
| `startDate` | ISO8601Date! | First day for which to fetch vulnerability history. |
### vulnerability
Find a vulnerability. Find a vulnerability.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | The Global ID of the Vulnerability. | VulnerabilityID! | | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | VulnerabilityID! | The Global ID of the Vulnerability. |
## Object types ## Object types
......
lib/gitlab/graphql/docs/helper.rb
View file @ dd534ff4
...@@ -28,7 +28,7 @@ module Gitlab ...@@ -28,7 +28,7 @@ module Gitlab
end end
def render_name_and_description(object) def render_name_and_description(object)
content = "### #{object[:name].camelcase}\n" content = "### #{object[:name]}\n"
if object[:description].present? if object[:description].present?
content += "\n#{object[:description]}" content += "\n#{object[:description]}"
...@@ -53,14 +53,6 @@ module Gitlab ...@@ -53,14 +53,6 @@ module Gitlab
] ]
end end
def render_argument(argument)
'| %s | %s | %s |' % [
render_name(argument),
render_description(argument),
render_field_type(argument[:type][:info])
]
end
def render_enum_value(value) def render_enum_value(value)
'| %s | %s |' % [ '| %s | %s |' % [
render_name(value), render_name(value),
......
lib/gitlab/graphql/docs/templates/default.md.haml
View file @ dd534ff4
...@@ -21,21 +21,19 @@ ...@@ -21,21 +21,19 @@
\ \
:plain :plain
## Queries ## `Query` type
Queries are used to get the resources, filter or query them. The `Query` type contains the API's top-level entry points for all executable queries.
For more information, visit [Queries and Mutations](https://graphql.org/learn/queries/).
\ \
- sorted_by_name(queries).each do |query| - sorted_by_name(queries).each do |query|
= render_name_and_description(query) = render_name_and_description(query)
- unless query[:arguments].empty? - unless query[:arguments].empty?
~ "| Name | Description | Type |" ~ "#### Arguments\n"
~ "| ----- | ---- | ----------- |" ~ "| Name | Type | Description |"
~ "| ---- | ---- | ----------- |"
- sorted_by_name(query[:arguments]).each do |argument| - sorted_by_name(query[:arguments]).each do |argument|
= render_argument(argument) = render_field(argument)
\ \
:plain :plain
......
spec/lib/gitlab/graphql/docs/renderer_spec.rb
View file @ dd534ff4
...@@ -53,13 +53,15 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do ...@@ -53,13 +53,15 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
context 'query generation' do context 'query generation' do
let(:expectation) do let(:expectation) do
<<~DOC <<~DOC
### Foo ### foo
List of objects. List of objects.
| Name | Description | Type | #### Arguments
| ----- | ---- | ----------- |
| `id` | ID of the object. | ID | | Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | ID | ID of the object. |
DOC DOC
end end
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7