Merge branch 'ajk-linked-graphql-docs-with-args' into 'master'

Linked GraphQL docs output

See merge request gitlab-org/gitlab!55944

app/graphql/mutations/labels/create.rb

@@ -23,7 +23,11 @@ module Mutations
       argument :color, GraphQL::STRING_TYPE,
                required: false,
                default_value: Label::DEFAULT_COLOR,
-               description: "The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the CSS color names in https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords."
+               description: <<~DESC
+                 The color of the label given in 6-digit hex notation with leading '#' sign
+                 (for example, `#FFAABB`) or one of the CSS color names
+                 <https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords>.
+               DESC
 
       authorize :admin_label
 

app/graphql/resolvers/concerns/issue_resolver_arguments.rb

@@ -7,57 +7,57 @@ module IssueResolverArguments
     include LooksAhead
 
     argument :iid, GraphQL::STRING_TYPE,
-              required: false,
-              description: 'IID of the issue. For example, "1".'
+             required: false,
+             description: 'IID of the issue. For example, "1".'
     argument :iids, [GraphQL::STRING_TYPE],
-              required: false,
-              description: 'List of IIDs of issues. For example, [1, 2].'
+             required: false,
+             description: 'List of IIDs of issues. For example, ["1", "2"].'
     argument :label_name, [GraphQL::STRING_TYPE, null: true],
-              required: false,
-              description: 'Labels applied to this issue.'
+             required: false,
+             description: 'Labels applied to this issue.'
     argument :milestone_title, [GraphQL::STRING_TYPE, null: true],
-              required: false,
-              description: 'Milestone applied to this issue.'
+             required: false,
+             description: 'Milestone applied to this issue.'
     argument :author_username, GraphQL::STRING_TYPE,
-              required: false,
-              description: 'Username of the author of the issue.'
+             required: false,
+             description: 'Username of the author of the issue.'
     argument :assignee_username, GraphQL::STRING_TYPE,
-              required: false,
-              description: 'Username of a user assigned to the issue.',
-              deprecated: { reason: 'Use `assigneeUsernames`', milestone: '13.11' }
+             required: false,
+             description: 'Username of a user assigned to the issue.',
+             deprecated: { reason: 'Use `assigneeUsernames`', milestone: '13.11' }
     argument :assignee_usernames, [GraphQL::STRING_TYPE],
-              required: false,
-              description: 'Usernames of users assigned to the issue.'
+             required: false,
+             description: 'Usernames of users assigned to the issue.'
     argument :assignee_id, GraphQL::STRING_TYPE,
-              required: false,
-              description: 'ID of a user assigned to the issues, "none" and "any" values are supported.'
+             required: false,
+             description: 'ID of a user assigned to the issues, "none" and "any" values are supported.'
     argument :created_before, Types::TimeType,
-              required: false,
-              description: 'Issues created before this date.'
+             required: false,
+             description: 'Issues created before this date.'
     argument :created_after, Types::TimeType,
-              required: false,
-              description: 'Issues created after this date.'
+             required: false,
+             description: 'Issues created after this date.'
     argument :updated_before, Types::TimeType,
-              required: false,
-              description: 'Issues updated before this date.'
+             required: false,
+             description: 'Issues updated before this date.'
     argument :updated_after, Types::TimeType,
-              required: false,
-              description: 'Issues updated after this date.'
+             required: false,
+             description: 'Issues updated after this date.'
     argument :closed_before, Types::TimeType,
-              required: false,
-              description: 'Issues closed before this date.'
+             required: false,
+             description: 'Issues closed before this date.'
     argument :closed_after, Types::TimeType,
-              required: false,
-              description: 'Issues closed after this date.'
+             required: false,
+             description: 'Issues closed after this date.'
     argument :search, GraphQL::STRING_TYPE,
-              required: false,
-              description: 'Search query for issue title or description.'
+             required: false,
+             description: 'Search query for issue title or description.'
     argument :types, [Types::IssueTypeEnum],
-              as: :issue_types,
-              description: 'Filter issues by the given issue types.',
-              required: false
+             as: :issue_types,
+             description: 'Filter issues by the given issue types.',
+             required: false
     argument :not, Types::Issues::NegatedIssueFilterInputType,
-             description: 'List of negated params.',
+             description: 'Negated arguments.',
              prepare: ->(negated_args, ctx) { negated_args.to_h },
              required: false
   end

changelogs/unreleased/ajk-linked-graphql-docs-with-args.yml

+---
+title: Add missing parts of GraphQL schema to GraphQL documentation
+merge_request: 55944
+author:
+type: changed

doc/api/vulnerabilities.md

@@ -18,7 +18,7 @@ WARNING:
 This API is in the process of being deprecated and considered unstable.
 The response payload may be subject to change or breakage
 across GitLab releases. Please use the
-[GraphQL API](graphql/reference/index.md#vulnerabilities)
+[GraphQL API](graphql/reference/index.md#queryvulnerabilities)
 instead.
 
 Every API call to vulnerabilities must be [authenticated](README.md#authentication).

ee/app/graphql/types/boards/board_epic_input_type.rb

@@ -10,7 +10,10 @@ module Types
 
       argument :not, NegatedEpicBoardIssueInputType,
                required: false,
-               description: 'List of epic negated params. Warning: this argument is experimental and a subject to change in the future.'
+               description: <<~DESC
+                 Negated epic arguments.
+                 Warning: this argument is experimental and a subject to change in the future.
+               DESC
 
       argument :search, GraphQL::STRING_TYPE,
                required: false,

lib/gitlab/graphql/deprecation.rb

@@ -41,7 +41,7 @@ module Gitlab
         parts = [
           "#{deprecated_in(format: :markdown)}.",
           reason_text,
-          replacement.then { |r| "Use: `#{r}`." if r }
+          replacement.then { |r| "Use: [`#{r}`](##{r.downcase.tr('.', '')})." if r }
         ].compact
 
         case context

lib/gitlab/graphql/docs/renderer.rb

@@ -24,6 +24,7 @@ module Gitlab
           @layout = Haml::Engine.new(File.read(template))
           @parsed_schema = GraphQLDocs::Parser.new(schema.graphql_definition, {}).parse
           @schema = schema
+          @seen = Set.new
         end
 
         def contents
@@ -37,6 +38,16 @@ module Gitlab
           FileUtils.mkdir_p(@output_dir)
           File.write(filename, contents)
         end
+
+        private
+
+        def seen_type?(name)
+          @seen.include?(name)
+        end
+
+        def seen_type!(name)
+          @seen << name
+        end
       end
     end
   end

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -26,17 +26,81 @@
   The `Query` type contains the API's top-level entry points for all executable queries.
 \
 
-- sorted_by_name(queries).each do |query|
-  = render_name_and_description(query, owner: 'Query')
-  \
-  = render_return_type(query)
-  - unless query[:arguments].empty?
-    ~ "#### Arguments\n"
-    ~ "| Name | Type | Description |"
-    ~ "| ---- | ---- | ----------- |"
-    - sorted_by_name(query[:arguments]).each do |argument|
-      = render_field(argument, query[:type][:name])
-    \
+- fields_of('Query').each do |field|
+  = render_full_field(field, heading_level: 3, owner: 'Query')
+  \
+
+:plain
+  ## `Mutation` type
+
+  The `Mutation` type contains all the mutations you can execute.
+
+  All mutations receive their arguments in a single input object named `input`, and all mutations
+  support at least a return field `errors` containing a list of error messages.
+
+  All input objects may have a `clientMutationId: String` field, identifying the mutation.
+
+  For example:
+
+  ```graphql
+  mutation($id: NoteableID!, $body: String!) {
+    createNote(input: { noteableId: $id, body: $body }) {
+      errors
+    }
+  }
+  ```
+\
+
+- mutations.each do |field|
+  = render_full_field(field, heading_level: 3, owner: 'Mutation')
+  \
+
+:plain
+  ## Connections
+
+  Some types in our schema are `Connection` types - they represent a paginated
+  collection of edges between two nodes in the graph. These follow the
+  [Relay cursor connections specification](https://relay.dev/graphql/connections.htm).
+
+  ### Pagination arguments {#connection-pagination-arguments}
+
+  All connection fields support the following pagination arguments:
+
+  | Name | Type | Description |
+  |------|------|-------------|
+  | `after` | [`String`](#string) | Returns the elements in the list that come after the specified cursor. |
+  | `before` | [`String`](#string) | Returns the elements in the list that come before the specified cursor. |
+  | `first` | [`Int`](#int) | Returns the first _n_ elements from the list. |
+  | `last` | [`Int`](#int) | Returns the last _n_ elements from the list. |
+
+  Since these arguments are common to all connection fields, they are not repeated for each connection.
+
+  ### Connection fields
+
+  All connections have at least the following fields:
+
+  | Name | Type | Description |
+  |------|------|-------------|
+  | `pageInfo` | [`PageInfo!`](#pageinfo) | Pagination information. |
+  | `edges` | `[edge!]` | The edges. |
+  | `nodes` | `[item!]` | The items in the current page. |
+
+  The precise type of `Edge` and `Item` depends on the kind of connection. A
+  [`UserConnection`](#userconnection) will have nodes that have the type
+  [`[User!]`](#user), and edges that have the type [`UserEdge`](#useredge).
+
+  ### Connection types
+
+  Some of the types in the schema exist solely to model connections. Each connection
+  has a distinct, named type, with a distinct named edge type. These are listed separately
+  below.
+\
+
+- connection_object_types.each do |type|
+  = render_name_and_description(type, level: 4)
+  \
+  = render_object_fields(type[:fields], owner: type, level_bump: 1)
+  \
 
 :plain
   ## Object types
@@ -44,22 +108,20 @@
   Object types represent the resources that the GitLab GraphQL API can return.
   They contain _fields_. Each field has its own type, which will either be one of the
   basic GraphQL [scalar types](https://graphql.org/learn/schema/#scalar-types)
-  (e.g.: `String` or `Boolean`) or other object types.
+  (e.g.: `String` or `Boolean`) or other object types. Fields may have arguments.
+  Fields with arguments are exactly like top-level queries, and are listed beneath
+  the table of fields for each object type.
 
   For more information, see
   [Object Types and Fields](https://graphql.org/learn/schema/#object-types-and-fields)
   on `graphql.org`.
 \
 
-- objects.each do |type|
-  - unless type[:fields].empty?
-    = render_name_and_description(type)
-    \
-    ~ "| Field | Type | Description |"
-    ~ "| ----- | ---- | ----------- |"
-    - sorted_by_name(type[:fields]).each do |field|
-      = render_field(field, type[:name])
-    \
+- object_types.each do |type|
+  = render_name_and_description(type)
+  \
+  = render_object_fields(type[:fields], owner: type)
+  \
 
 :plain
   ## Enumeration types
@@ -73,14 +135,13 @@
 \
 
 - enums.each do |enum|
-  - unless enum[:values].empty?
-    = render_name_and_description(enum)
-    \
-    ~ "| Value | Description |"
-    ~ "| ----- | ----------- |"
-    - sorted_by_name(enum[:values]).each do |value|
-      = render_enum_value(enum, value)
-    \
+  = render_name_and_description(enum)
+  \
+  ~ "| Value | Description |"
+  ~ "| ----- | ----------- |"
+  - enum[:values].each do |value|
+    = render_enum_value(enum, value)
+  \
 
 :plain
   ## Scalar types
@@ -133,7 +194,7 @@
   ### Interfaces
 \
 
-- graphql_interface_types.each do |type|
+- interfaces.each do |type|
   = render_name_and_description(type, level: 4)
   \
   Implementations:
@@ -141,8 +202,21 @@
   - type[:implemented_by].each do |type_name|
     ~ "- [`#{type_name}`](##{type_name.downcase})"
   \
-  ~ "| Field | Type | Description |"
-  ~ "| ----- | ---- | ----------- |"
-  - sorted_by_name(type[:fields] + type[:connections]).each do |field|
-    = render_field(field, type[:name])
+  = render_object_fields(type[:fields], owner: type, level_bump: 1)
+  \
+
+:plain
+  ## Input types
+
+  Types that may be used as arguments (all scalar types may also
+  be used as arguments).
+
+  Only general use input types are listed here. For mutation input types,
+  see the associated mutation type above.
+\
+
+- input_types.each do |type|
+  = render_name_and_description(type)
+  \
+  = render_argument_table(3, type[:input_fields], type[:name])
   \

spec/lib/gitlab/graphql/deprecation_spec.rb

@@ -164,7 +164,7 @@ RSpec.describe ::Gitlab::Graphql::Deprecation do
 
       context 'when the context is :inline' do
         it 'renders on one line' do
-          expectation = '**Deprecated** in 10.10. This was renamed. Use: `X.y`.'
+          expectation = '**Deprecated** in 10.10. This was renamed. Use: [`X.y`](#xy).'
 
           expect(deprecation.markdown).to eq(expectation)
           expect(deprecation.markdown(context: :inline)).to eq(expectation)
@@ -177,7 +177,7 @@ RSpec.describe ::Gitlab::Graphql::Deprecation do
             WARNING:
             **Deprecated** in 10.10.
             This was renamed.
-            Use: `X.y`.
+            Use: [`X.y`](#xy).
           MD
 
           expect(deprecation.markdown(context: :block)).to eq(expectation)