Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
d7fd06fc
Commit
d7fd06fc
authored
Feb 08, 2021
by
Jarka Košanová
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Add queriess to auto-generated graphqL docs
- change renderer and templatee - regenerate the docs
parent
b3930ff7
Changes
10
Show whitespace changes
Inline
Side-by-side
Showing
10 changed files
with
236 additions
and
23 deletions
+236
-23
app/graphql/resolvers/ci/config_resolver.rb
app/graphql/resolvers/ci/config_resolver.rb
+1
-1
app/graphql/resolvers/full_path_resolver.rb
app/graphql/resolvers/full_path_resolver.rb
+1
-1
app/graphql/types/query_type.rb
app/graphql/types/query_type.rb
+1
-1
changelogs/unreleased/30010-graphql-doc.yml
changelogs/unreleased/30010-graphql-doc.yml
+5
-0
doc/api/graphql/reference/gitlab_schema.graphql
doc/api/graphql/reference/gitlab_schema.graphql
+5
-5
doc/api/graphql/reference/gitlab_schema.json
doc/api/graphql/reference/gitlab_schema.json
+5
-5
doc/api/graphql/reference/index.md
doc/api/graphql/reference/index.md
+148
-4
lib/gitlab/graphql/docs/helper.rb
lib/gitlab/graphql/docs/helper.rb
+18
-2
lib/gitlab/graphql/docs/templates/default.md.haml
lib/gitlab/graphql/docs/templates/default.md.haml
+18
-0
spec/lib/gitlab/graphql/docs/renderer_spec.rb
spec/lib/gitlab/graphql/docs/renderer_spec.rb
+34
-4
No files found.
app/graphql/resolvers/ci/config_resolver.rb
View file @
d7fd06fc
...
...
@@ -16,7 +16,7 @@ module Resolvers
argument
:content
,
GraphQL
::
STRING_TYPE
,
required:
true
,
description:
"Contents of
'.gitlab-ci.yml'
."
description:
"Contents of
`.gitlab-ci.yml`
."
argument
:dry_run
,
GraphQL
::
BOOLEAN_TYPE
,
required:
false
,
...
...
app/graphql/resolvers/full_path_resolver.rb
View file @
d7fd06fc
...
...
@@ -7,7 +7,7 @@ module Resolvers
prepended
do
argument
:full_path
,
GraphQL
::
ID_TYPE
,
required:
true
,
description:
'The full path of the project, group or namespace, e.g.,
"gitlab-org/gitlab-foss"
.'
description:
'The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
.'
end
def
model_by_full_path
(
model
,
full_path
)
...
...
app/graphql/types/query_type.rb
View file @
d7fd06fc
...
...
@@ -78,7 +78,7 @@ module Types
field
:issue
,
Types
::
IssueType
,
null:
true
,
description:
'Find an
i
ssue.'
do
description:
'Find an
I
ssue.'
do
argument
:id
,
::
Types
::
GlobalIDType
[
::
Issue
],
required:
true
,
description:
'The global ID of the Issue.'
end
...
...
changelogs/unreleased/30010-graphql-doc.yml
0 → 100644
View file @
d7fd06fc
---
title
:
Add documentation for graphQL queries
merge_request
:
54302
author
:
type
:
other
doc/api/graphql/reference/gitlab_schema.graphql
View file @
d7fd06fc
...
...
@@ -21475,7 +21475,7 @@ type Query {
"""
ciConfig
(
"""
Contents
of
'.
gitlab
-
ci
.
yml
'
.
Contents
of
`.
gitlab
-
ci
.
yml
`
.
"""
content
:
String
!
...
...
@@ -21560,7 +21560,7 @@ type Query {
"""
group
(
"""
The
full
path
of
the
project
,
group
or
namespace
,
e
.
g
.
,
"
gitlab
-
org
/
gitlab
-
foss
"
.
The
full
path
of
the
project
,
group
or
namespace
,
e
.
g
.
,
`
gitlab
-
org
/
gitlab
-
foss
`
.
"""
fullPath
:
ID
!
):
Group
...
...
@@ -21611,7 +21611,7 @@ type Query {
):
InstanceStatisticsMeasurementConnection
"""
Find
an
i
ssue
.
Find
an
I
ssue
.
"""
issue
(
"""
...
...
@@ -21650,7 +21650,7 @@ type Query {
"""
namespace
(
"""
The
full
path
of
the
project
,
group
or
namespace
,
e
.
g
.
,
"
gitlab
-
org
/
gitlab
-
foss
"
.
The
full
path
of
the
project
,
group
or
namespace
,
e
.
g
.
,
`
gitlab
-
org
/
gitlab
-
foss
`
.
"""
fullPath
:
ID
!
):
Namespace
...
...
@@ -21670,7 +21670,7 @@ type Query {
"""
project
(
"""
The
full
path
of
the
project
,
group
or
namespace
,
e
.
g
.
,
"
gitlab
-
org
/
gitlab
-
foss
"
.
The
full
path
of
the
project
,
group
or
namespace
,
e
.
g
.
,
`
gitlab
-
org
/
gitlab
-
foss
`
.
"""
fullPath
:
ID
!
):
Project
...
...
doc/api/graphql/reference/gitlab_schema.json
View file @
d7fd06fc
...
...
@@ -62232,7 +62232,7 @@
},
{
"name": "content",
"description": "Contents of
'.gitlab-ci.yml'
.",
"description": "Contents of
`.gitlab-ci.yml`
.",
"type": {
"kind": "NON_NULL",
"name": null,
...
...
@@ -62435,7 +62435,7 @@
"args": [
{
"name": "fullPath",
"description": "The full path of the project, group or namespace, e.g.,
\"gitlab-org/gitlab-foss\"
.",
"description": "The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
.",
"type": {
"kind": "NON_NULL",
"name": null,
...
...
@@ -62559,7 +62559,7 @@
},
{
"name": "issue",
"description": "Find an
i
ssue.",
"description": "Find an
I
ssue.",
"args": [
{
"name": "id",
...
...
@@ -62658,7 +62658,7 @@
"args": [
{
"name": "fullPath",
"description": "The full path of the project, group or namespace, e.g.,
\"gitlab-org/gitlab-foss\"
.",
"description": "The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
.",
"type": {
"kind": "NON_NULL",
"name": null,
...
...
@@ -62712,7 +62712,7 @@
"args": [
{
"name": "fullPath",
"description": "The full path of the project, group or namespace, e.g.,
\"gitlab-org/gitlab-foss\"
.",
"description": "The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
.",
"type": {
"kind": "NON_NULL",
"name": null,
doc/api/graphql/reference/index.md
View file @
d7fd06fc
...
...
@@ -26,6 +26,150 @@ in [Removed Items](../removed_items.md).
<!-- vale gitlab.Spelling = NO -->
## Queries
Queries are used to get the resources, filter or query them.
For more information, visit
[
Queries and Mutations
](
https://graphql.org/learn/queries/
)
.
### CiApplicationSettings
CI related settings that apply to the entire instance.
### CiConfig
Get linted and processed contents of a CI config. Should not be requested more than once per request.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`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
Find a container repository.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| The global ID of the container repository. | ContainerRepositoryID! |
### CurrentUser
Get information about current user.
### DesignManagement
Fields related to design management.
### Echo
Text to echo back.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`text`
| Text to echo back. | String! |
### GeoNode
Find a Geo node.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`name`
| The name of the Geo node. Defaults to the current Geo node name. | String |
### Group
Find a group.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`fullPath`
| The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
. | ID! |
### InstanceSecurityDashboard
Fields related to Instance Security Dashboard.
### Issue
Find an Issue.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| The global ID of the Issue. | IssueID! |
### Iteration
Find an iteration.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| Find an iteration by its ID. | IterationID! |
### Metadata
Metadata about GitLab.
### Milestone
Find a milestone.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| Find a milestone by its ID. | MilestoneID! |
### Namespace
Find a namespace.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`fullPath`
| The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
. | ID! |
### Package
Find a package.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| The global ID of the package. | PackagesPackageID! |
### Project
Find a project.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`fullPath`
| The full path of the project, group or namespace, e.g.,
`gitlab-org/gitlab-foss`
. | ID! |
### RunnerSetup
Get runner setup instructions.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`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 |
### User
Find a user.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| ID of the User. | UserID |
|
`username`
| Username of the User. | String |
### Vulnerability
Find a vulnerability.
| Name | Description | Type |
| ----- | ---- | ----------- |
|
`id`
| The Global ID of the Vulnerability. | VulnerabilityID! |
## Object types
Object types represent the resources that the GitLab GraphQL API can return.
...
...
@@ -204,7 +348,7 @@ Autogenerated return type of ApiFuzzingCiConfigurationCreate.
### ApiFuzzingScanProfile
An API Fuzzing scan profile.
.
An API Fuzzing scan profile.
| Field | Type | Description |
| ----- | ---- | ----------- |
...
...
@@ -1955,7 +2099,7 @@ Describes an incident management on-call schedule.
### IncidentManagementOncallShift
A block of time for which a participant is on-call.
.
A block of time for which a participant is on-call.
| Field | Type | Description |
| ----- | ---- | ----------- |
...
...
@@ -2780,7 +2924,7 @@ Represents a version of a package in the Package Registry.
### PageInfo
Information about pagination in a connection.
.
Information about pagination in a connection.
| Field | Type | Description |
| ----- | ---- | ----------- |
...
...
@@ -5116,7 +5260,7 @@ Possible identifier types for a measurement.
### MergeRequestNewState
New state to apply to a merge request.
.
New state to apply to a merge request.
| Value | Description |
| ----- | ----------- |
...
...
lib/gitlab/graphql/docs/helper.rb
View file @
d7fd06fc
...
...
@@ -28,16 +28,20 @@ module Gitlab
end
def
render_name_and_description
(
object
)
content
=
"###
#{
object
[
:name
]
}
\n
"
content
=
"###
#{
object
[
:name
]
.
camelcase
}
\n
"
if
object
[
:description
].
present?
content
+=
"
\n
#{
object
[
:description
]
}
.
\n
"
content
+=
"
\n
#{
object
[
:description
]
}
"
content
+=
'.'
unless
object
[
:description
].
ends_with?
(
'.'
)
content
+=
"
\n
"
end
content
end
def
sorted_by_name
(
objects
)
return
[]
unless
objects
.
present?
objects
.
sort_by
{
|
o
|
o
[
:name
]
}
end
...
...
@@ -49,6 +53,14 @@ module Gitlab
]
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
)
'| %s | %s |'
%
[
render_name
(
value
),
...
...
@@ -98,6 +110,10 @@ module Gitlab
end
end
def
queries
graphql_operation_types
.
find
{
|
type
|
type
[
:name
]
==
'Query'
}.
to_h
[
:fields
]
end
# We ignore the built-in enum types.
def
enums
graphql_enum_types
.
select
do
|
enum_type
|
...
...
lib/gitlab/graphql/docs/templates/default.md.haml
View file @
d7fd06fc
...
...
@@ -20,6 +20,24 @@
<!-- vale gitlab.Spelling = NO -->
\
:plain
## Queries
Queries are used to get the resources, filter or query them.
For more information, visit [Queries and Mutations](https://graphql.org/learn/queries/).
\
-
sorted_by_name
(
queries
).
each
do
|
query
|
=
render_name_and_description
(
query
)
-
unless
query
[
:arguments
].
empty?
~ "| Name | Description | Type |"
~ "| ----- | ---- | ----------- |"
-
sorted_by_name
(
query
[
:arguments
]).
each
do
|
argument
|
=
render_argument
(
argument
)
\
:plain
## Object types
...
...
spec/lib/gitlab/graphql/docs/renderer_spec.rb
View file @
d7fd06fc
...
...
@@ -5,21 +5,25 @@ require 'spec_helper'
RSpec
.
describe
Gitlab
::
Graphql
::
Docs
::
Renderer
do
describe
'#contents'
do
# Returns a Schema that uses the given `type`
def
mock_schema
(
type
)
def
mock_schema
(
type
,
field_description
)
query_type
=
Class
.
new
(
Types
::
BaseObject
)
do
graphql_name
'Query
Type
'
graphql_name
'Query'
field
:foo
,
type
,
null:
true
field
:foo
,
type
,
null:
true
do
description
field_description
argument
:id
,
GraphQL
::
ID_TYPE
,
required:
false
,
description:
'ID of the object.'
end
end
GraphQL
::
Schema
.
define
(
query:
query_type
)
end
let_it_be
(
:template
)
{
Rails
.
root
.
join
(
'lib/gitlab/graphql/docs/templates/'
,
'default.md.haml'
)
}
let
(
:field_description
)
{
'List of objects.'
}
subject
(
:contents
)
do
described_class
.
new
(
mock_schema
(
type
).
graphql_definition
,
mock_schema
(
type
,
field_description
).
graphql_definition
,
output_dir:
nil
,
template:
template
).
contents
...
...
@@ -45,6 +49,32 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
is_expected
.
to
include
(
expectation
)
end
context
'query generation'
do
let
(
:expectation
)
do
<<~
DOC
### Foo
List of objects.
| Name | Description | Type |
| ----- | ---- | ----------- |
| `id` | ID of the object. | ID |
DOC
end
it
'generates the query with arguments'
do
expect
(
subject
).
to
include
(
expectation
)
end
context
'when description does not end with `.`'
do
let
(
:field_description
)
{
'List of objects'
}
it
'adds the `.` to the end'
do
expect
(
subject
).
to
include
(
expectation
)
end
end
end
end
context
'A type with fields defined in reverse alphabetical order'
do
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment