Merge branch '30010-graphql-doc' into 'master'

Add queriess to auto-generated graphqL docs

See merge request gitlab-org/gitlab!54302

app/graphql/resolvers/ci/config_resolver.rb

@@ -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

@@ -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

@@ -78,7 +78,7 @@ module Types
 
     field :issue, Types::IssueType,
           null: true,
-          description: 'Find an issue.' do
+          description: 'Find an Issue.' do
             argument :id, ::Types::GlobalIDType[::Issue], required: true, description: 'The global ID of the Issue.'
           end
 

changelogs/unreleased/30010-graphql-doc.yml

+---
+title: Add documentation for graphQL queries
+merge_request: 54302
+author:
+type: other

doc/api/graphql/reference/gitlab_schema.graphql

@@ -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 issue.
+  Find an Issue.
   """
   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

@@ -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 issue.",
+              "description": "Find an Issue.",
               "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

@@ -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

@@ -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

@@ -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

@@ -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 'QueryType'
+        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