Argument deprecation

Author: jturkel

guides/fields/arguments.md

@@ -62,6 +62,16 @@ def search_posts(category:)
 end
 ```
 
+**Experimental:** __Deprecated__ arguments can be marked by adding a `deprecation_reason:` keyword argument:
+
+```ruby
+field :search_posts, [PostType], null: false do
+  argument :name, String, required: false, deprecation_reason: "Use `query` instead."
+  argument :query, String, required: false
+end
+```
+Note argument deprecation is a stage 2 GraphQL [proposal](https://github.com/graphql/graphql-spec/pull/525) so not all clients will leverage this information.
+
 Use `as: :alternate_name` to use a different key from within your resolvers while
 exposing another key to clients.
 

lib/graphql/argument.rb

@@ -3,14 +3,14 @@ module GraphQL
   # @api deprecated
   class Argument
     include GraphQL::Define::InstanceDefinable
-    accepts_definitions :name, :type, :description, :default_value, :as, :prepare, :method_access
+    accepts_definitions :name, :type, :description, :default_value, :as, :prepare, :method_access, :deprecation_reason
     attr_reader :default_value
-    attr_accessor :description, :name, :as
+    attr_accessor :description, :name, :as, :deprecation_reason
     attr_accessor :ast_node
     attr_accessor :method_access
     alias :graphql_name :name
 
-    ensure_defined(:name, :description, :default_value, :type=, :type, :as, :expose_as, :prepare, :method_access)
+    ensure_defined(:name, :description, :default_value, :type=, :type, :as, :expose_as, :prepare, :method_access, :deprecation_reason)
 
     # @api private
     module DefaultPrepare

lib/graphql/introspection.rb

@@ -1,6 +1,102 @@
 # frozen_string_literal: true
 module GraphQL
   module Introspection
+    def self.query(include_deprecated_args: false)
+      # The introspection query to end all introspection queries, copied from
+      # https://github.com/graphql/graphql-js/blob/master/src/utilities/introspectionQuery.js
+      <<-QUERY
+query IntrospectionQuery {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    subscriptionType { name }
+    types {
+      ...FullType
+    }
+    directives {
+      name
+      description
+      locations
+      args {
+        ...InputValue
+      }
+    }
+  }
+}
+fragment FullType on __Type {
+  kind
+  name
+  description
+  fields(includeDeprecated: true) {
+    name
+    description
+    args#{include_deprecated_args ? '(includeDeprecated: true)' : ''} {
+      ...InputValue
+    }
+    type {
+      ...TypeRef
+    }
+    isDeprecated
+    deprecationReason
+  }
+  inputFields#{include_deprecated_args ? '(includeDeprecated: true)' : ''} {
+    ...InputValue
+  }
+  interfaces {
+    ...TypeRef
+  }
+  enumValues(includeDeprecated: true) {
+    name
+    description
+    isDeprecated
+    deprecationReason
+  }
+  possibleTypes {
+    ...TypeRef
+  }
+}
+fragment InputValue on __InputValue {
+  name
+  description
+  type { ...TypeRef }
+  defaultValue
+  #{include_deprecated_args ? 'isDeprecated' : ''}
+  #{include_deprecated_args ? 'deprecationReason' : ''}
+}
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+      QUERY
+    end
   end
 end
 

lib/graphql/introspection/field_type.rb

@@ -7,7 +7,9 @@ class FieldType < Introspection::BaseObject
                   "a name, potentially a list of arguments, and a return type."
       field :name, String, null: false
       field :description, String, null: true
-      field :args, [GraphQL::Schema::LateBoundType.new("__InputValue")], null: false
+      field :args, [GraphQL::Schema::LateBoundType.new("__InputValue")], null: false do
+        argument :include_deprecated, Boolean, required: false, default_value: false
+      end
       field :type, GraphQL::Schema::LateBoundType.new("__Type"), null: false
       field :is_deprecated, Boolean, null: false
       field :deprecation_reason, String, null: true
@@ -16,8 +18,10 @@ def is_deprecated
         !!@object.deprecation_reason
       end
 
-      def args
-        @context.warden.arguments(@object)
+      def args(include_deprecated:)
+        args = @context.warden.arguments(@object)
+        args = args.reject(&:deprecation_reason) unless include_deprecated
+        args
       end
     end
   end

lib/graphql/introspection/input_value_type.rb

@@ -10,6 +10,12 @@ class InputValueType < Introspection::BaseObject
       field :description, String, null: true
       field :type, GraphQL::Schema::LateBoundType.new("__Type"), null: false
       field :default_value, String, "A GraphQL-formatted string representing the default value for this input value.", null: true
+      field :is_deprecated, Boolean, null: false
+      field :deprecation_reason, String, null: true
+
+      def is_deprecated
+        !!@object.deprecation_reason
+      end
 
       def default_value
         if @object.default_value?

lib/graphql/introspection/introspection_query.rb

@@ -1,93 +1,7 @@
 # frozen_string_literal: true
-# The introspection query to end all introspection queries, copied from
-# https://github.com/graphql/graphql-js/blob/master/src/utilities/introspectionQuery.js
-GraphQL::Introspection::INTROSPECTION_QUERY = "
-query IntrospectionQuery {
-  __schema {
-    queryType { name }
-    mutationType { name }
-    subscriptionType { name }
-    types {
-      ...FullType
-    }
-    directives {
-      name
-      description
-      locations
-      args {
-        ...InputValue
-      }
-    }
-  }
-}
-fragment FullType on __Type {
-  kind
-  name
-  description
-  fields(includeDeprecated: true) {
-    name
-    description
-    args {
-      ...InputValue
-    }
-    type {
-      ...TypeRef
-    }
-    isDeprecated
-    deprecationReason
-  }
-  inputFields {
-    ...InputValue
-  }
-  interfaces {
-    ...TypeRef
-  }
-  enumValues(includeDeprecated: true) {
-    name
-    description
-    isDeprecated
-    deprecationReason
-  }
-  possibleTypes {
-    ...TypeRef
-  }
-}
-fragment InputValue on __InputValue {
-  name
-  description
-  type { ...TypeRef }
-  defaultValue
-}
-fragment TypeRef on __Type {
-  kind
-  name
-  ofType {
-    kind
-    name
-    ofType {
-      kind
-      name
-      ofType {
-        kind
-        name
-        ofType {
-          kind
-          name
-          ofType {
-            kind
-            name
-            ofType {
-              kind
-              name
-              ofType {
-                kind
-                name
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-"
+
+# This query is used by graphql-client so don't add the includeDeprecated
+# argument for inputFields since the server may not support it. Two stage
+# introspection queries will be required to handle this in clients.
+GraphQL::Introspection::INTROSPECTION_QUERY = GraphQL::Introspection.query
+

lib/graphql/introspection/type_type.rb

@@ -22,7 +22,9 @@ class TypeType < Introspection::BaseObject
       field :enum_values, [GraphQL::Schema::LateBoundType.new("__EnumValue")], null: true do
         argument :include_deprecated, Boolean, required: false, default_value: false
       end
-      field :input_fields, [GraphQL::Schema::LateBoundType.new("__InputValue")], null: true
+      field :input_fields, [GraphQL::Schema::LateBoundType.new("__InputValue")], null: true  do
+        argument :include_deprecated, Boolean, required: false, default_value: false
+      end
       field :of_type, GraphQL::Schema::LateBoundType.new("__Type"), null: true
 
       def name
@@ -55,9 +57,11 @@ def interfaces
         end
       end
 
-      def input_fields
+      def input_fields(include_deprecated:)
         if @object.kind.input_object?
-          @context.warden.arguments(@object)
+          args = @context.warden.arguments(@object)
+          args = args.reject(&:deprecation_reason) unless include_deprecated
+          args
         else
           nil
         end

lib/graphql/schema.rb

@@ -832,7 +832,7 @@ def to_document(only: nil, except: nil, context: {})
     # @param except [<#call(member, ctx)>]
     # @return [Hash] GraphQL result
     def as_json(only: nil, except: nil, context: {})
-      execute(Introspection::INTROSPECTION_QUERY, only: only, except: except, context: context).to_h
+      execute(Introspection.query(include_deprecated_args: true), only: only, except: except, context: context).to_h
     end
 
     # Returns the JSON response of {Introspection::INTROSPECTION_QUERY}.
@@ -880,7 +880,7 @@ def to_json(**args)
       # @param except [<#call(member, ctx)>]
       # @return [Hash] GraphQL result
       def as_json(only: nil, except: nil, context: {})
-        execute(Introspection::INTROSPECTION_QUERY, only: only, except: except, context: context).to_h
+        execute(Introspection.query(include_deprecated_args: true), only: only, except: except, context: context).to_h
       end
 
       # Return the GraphQL IDL for the schema

lib/graphql/schema/argument.rb

@@ -45,7 +45,8 @@ def from_resolver?
       # @param camelize [Boolean] if true, the name will be camelized when building the schema
       # @param from_resolver [Boolean] if true, a Resolver class defined this argument
       # @param method_access [Boolean] If false, don't build method access on legacy {Query::Arguments} instances.
-      def initialize(arg_name = nil, type_expr = nil, desc = nil, required:, type: nil, name: nil, loads: nil, description: nil, ast_node: nil, default_value: NO_DEFAULT, as: nil, from_resolver: false, camelize: true, prepare: nil, method_access: true, owner:, &definition_block)
+      # @param deprecation_reason [String]
+      def initialize(arg_name = nil, type_expr = nil, desc = nil, required:, type: nil, name: nil, loads: nil, description: nil, ast_node: nil, default_value: NO_DEFAULT, as: nil, from_resolver: false, camelize: true, prepare: nil, method_access: true, owner:, deprecation_reason: nil, &definition_block)
         arg_name ||= name
         @name = -(camelize ? Member::BuildType.camelize(arg_name.to_s) : arg_name.to_s)
         @type_expr = type_expr || type
@@ -60,6 +61,7 @@ def initialize(arg_name = nil, type_expr = nil, desc = nil, required:, type: nil
         @ast_node = ast_node
         @from_resolver = from_resolver
         @method_access = method_access
+        @deprecation_reason = deprecation_reason
 
         if definition_block
           if definition_block.arity == 1
@@ -89,6 +91,17 @@ def description(text = nil)
         end
       end
 
+      attr_writer :deprecation_reason
+
+      # @return [String] Deprecation reason for this argument
+      def deprecation_reason(text = nil)
+        if text
+          @deprecation_reason = text
+        else
+          @deprecation_reason
+        end
+      end
+
       def visible?(context)
         true
       end
@@ -143,6 +156,9 @@ def to_graphql
         if NO_DEFAULT != @default_value
           argument.default_value = @default_value
         end
+        if @deprecation_reason
+          argument.deprecation_reason = @deprecation_reason
+        end
         argument
       end
 

lib/graphql/schema/build_from_definition.rb

@@ -261,6 +261,7 @@ def build_arguments(type_class, arguments, type_resolver)
               type: type_resolver.call(argument_defn.type),
               required: false,
               description: argument_defn.description,
+              deprecation_reason: builder.build_deprecation_reason(argument_defn.directives),
               ast_node: argument_defn,
               camelize: false,
               method_access: false,