Add missing parts to the GraphQL schema

This adds:

- mutations
- arguments
- input types

And ensures we can link to all fields, whether they are in a
field table or listed as a full field with arguments. Deprecations
are changed to link to the replacements.

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

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,14 @@ module Gitlab
           FileUtils.mkdir_p(@output_dir)
           File.write(filename, contents)
         end
+
+        def seen?(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])
-    \
+- queries.each do |query|
+  = render_full_field(query, heading_level: 3, owner: 'Query')
+  \
+
+:plain
+  ## `Mutation` type
+
+  The `Mutation` type contains the API's top-level entry points for all executable mutations.
+
+  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)