diff --git a/app/graphql/resolvers/ci/config_resolver.rb b/app/graphql/resolvers/ci/config_resolver.rb index 852bb47e21527255529b054de95bdea0ccf3a875..f8670649e48a07f5ebb261aff35e6a27dad66f59 100644 --- a/app/graphql/resolvers/ci/config_resolver.rb +++ b/app/graphql/resolvers/ci/config_resolver.rb @@ -16,7 +16,7 @@ class ConfigResolver < BaseResolver 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, diff --git a/app/graphql/resolvers/full_path_resolver.rb b/app/graphql/resolvers/full_path_resolver.rb index d01cdf749a1e8d8f8a55a2728de26b7216eea9ed..b5e90da78b22f578eb13e5b3ca861f585a36ae1f 100644 --- a/app/graphql/resolvers/full_path_resolver.rb +++ b/app/graphql/resolvers/full_path_resolver.rb @@ -7,7 +7,7 @@ module FullPathResolver 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) diff --git a/app/graphql/types/query_type.rb b/app/graphql/types/query_type.rb index 1d1ab4f2e179bd9f8ec9e568ff437370cbe930d1..95805d016f1327fc9d13c1fe90ac902a4b420ef6 100644 --- a/app/graphql/types/query_type.rb +++ b/app/graphql/types/query_type.rb @@ -78,7 +78,7 @@ class QueryType < ::Types::BaseObject 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 diff --git a/changelogs/unreleased/30010-graphql-doc.yml b/changelogs/unreleased/30010-graphql-doc.yml new file mode 100644 index 0000000000000000000000000000000000000000..bc4757e4c2429338a6cf75d9be3e6f0fbb2ee8af --- /dev/null +++ b/changelogs/unreleased/30010-graphql-doc.yml @@ -0,0 +1,5 @@ +--- +title: Add documentation for graphQL queries +merge_request: 54302 +author: +type: other diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 4e89f663efc97165e5bf39271f4db6bf453f4918..6a2efac7caa66a2dfc0e4bb452ca5282dc0b4ef5 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/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 diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 492682d2e54e00bcb0dbc7d018946d59f2ac9795..e9425d5b95e2e622dd1ccb01f1585fc6fd104bef 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/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, diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index f49a12568ed5b583c1a0041d60a13a75859e2e94..2b2b28e191b7e89150eb18878d3fead327e3b7ec 100644 --- a/doc/api/graphql/reference/index.md +++ b/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 | | ----- | ----------- | diff --git a/lib/gitlab/graphql/docs/helper.rb b/lib/gitlab/graphql/docs/helper.rb index ad9e08e189cbd6df23e5fcb24f2c7f3962c1d3e8..155602740c4823a1c91a7c26ee095ce421b4f81a 100644 --- a/lib/gitlab/graphql/docs/helper.rb +++ b/lib/gitlab/graphql/docs/helper.rb @@ -28,16 +28,20 @@ def auto_generated_comment 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 @@ def render_field(field) ] 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 @@ def objects 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| diff --git a/lib/gitlab/graphql/docs/templates/default.md.haml b/lib/gitlab/graphql/docs/templates/default.md.haml index 9dfb9b090a8247277d137a6674fb4f193e43fa54..1df1c3a3e58dcb90a3ca208a710571c4a1da9416 100644 --- a/lib/gitlab/graphql/docs/templates/default.md.haml +++ b/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 diff --git a/spec/lib/gitlab/graphql/docs/renderer_spec.rb b/spec/lib/gitlab/graphql/docs/renderer_spec.rb index 064e0c6828b0310f127893448aedfd04eacb89ce..2923e589ff72540dbc60d1379bf94c79d93d37a3 100644 --- a/spec/lib/gitlab/graphql/docs/renderer_spec.rb +++ b/spec/lib/gitlab/graphql/docs/renderer_spec.rb @@ -5,21 +5,25 @@ 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 @@ def mock_schema(type) 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