Add deprecations to IDL

Author: cjoudrey

lib/graphql/directive.rb

@@ -16,16 +16,19 @@ class Directive
       MUTATION =            :MUTATION,
       SUBSCRIPTION =        :SUBSCRIPTION,
       FIELD =               :FIELD,
+      FIELD_DEFINITION =    :FIELD_DEFINITION,
       FRAGMENT_DEFINITION = :FRAGMENT_DEFINITION,
       FRAGMENT_SPREAD =     :FRAGMENT_SPREAD,
       INLINE_FRAGMENT =     :INLINE_FRAGMENT,
+      ENUM_VALUE =          :ENUM_VALUE,
     ]
 
     def initialize
       @arguments = {}
     end
 
     def include?(arguments)
+      return true if include_proc.nil?
       include_proc.call(arguments)
     end
 
@@ -49,3 +52,4 @@ def on_operation?
 
 require "graphql/directive/include_directive"
 require "graphql/directive/skip_directive"
+require "graphql/directive/deprecated_directive"

lib/graphql/directive/deprecated_directive.rb

@@ -0,0 +1,11 @@
+GraphQL::Directive::DeprecatedDirective = GraphQL::Directive.define do
+  name "deprecated"
+  description "Marks an element of a GraphQL schema as no longer supported."
+  locations([GraphQL::Directive::FIELD_DEFINITION, GraphQL::Directive::ENUM_VALUE])
+
+  reason_description = "Explains why this element was deprecated, usually also including a "\
+    "suggestion for how to access supported similar data. Formatted "\
+    "in [Markdown](https://daringfireball.net/projects/markdown/)."
+
+  argument :reason, !GraphQL::STRING_TYPE, reason_description, default_value: "No longer supported"
+end

lib/graphql/schema.rb

@@ -61,7 +61,7 @@ class Schema
       :query_analyzers, :middleware
 
 
-    DIRECTIVES = [GraphQL::Directive::SkipDirective, GraphQL::Directive::IncludeDirective]
+    DIRECTIVES = [GraphQL::Directive::SkipDirective, GraphQL::Directive::IncludeDirective, GraphQL::Directive::DeprecatedDirective]
     DYNAMIC_FIELDS = ["__type", "__typename", "__schema"]
     RESOLVE_TYPE_PROC_REQUIRED = -> (obj, ctx) { raise("Schema.resolve_type is undefined, can't resolve type for #{obj.inspect}") }
 

lib/graphql/schema/printer.rb

@@ -12,7 +12,7 @@ module Printer
       # Return a GraphQL schema string for the defined types in the schema
       # @param schema [GraphQL::Schema]
       def print_schema(schema)
-        print_filtered_schema(schema, method(:is_defined_type))
+        print_filtered_schema(schema, lambda { |n| !is_spec_directive(n) }, method(:is_defined_type))
       end
 
       # Return the GraphQL schema string for the introspection type system
@@ -21,16 +21,20 @@ def print_introspection_schema
           name "Query"
         end
         schema = GraphQL::Schema.define(query: query_root)
-        print_filtered_schema(schema, method(:is_introspection_type))
+        print_filtered_schema(schema, method(:is_spec_directive), method(:is_introspection_type))
       end
 
       private
 
-      def print_filtered_schema(schema, type_filter)
+      def print_filtered_schema(schema, directive_filter, type_filter)
+        directives = schema.directives.values.select{ |directive| directive_filter.call(directive) }
+        directive_definitions = directives.map{ |directive| print_directive(directive) }
+
         types = schema.types.values.select{ |type| type_filter.call(type) }.sort_by(&:name)
         type_definitions = types.map{ |type| print_type(type) }
 
-        [print_schema_definition(schema)].concat(type_definitions).join("\n\n")
+        [print_schema_definition(schema)].concat(directive_definitions)
+                                         .concat(type_definitions).join("\n\n")
       end
 
       def print_schema_definition(schema)
@@ -44,6 +48,10 @@ def print_schema_definition(schema)
       BUILTIN_SCALARS = Set.new(["String", "Boolean", "Int", "Float", "ID"])
       private_constant :BUILTIN_SCALARS
 
+      def is_spec_directive(directive)
+        ['skip', 'include', 'deprecated'].include?(directive.name)
+      end
+
       def is_introspection_type(type)
         type.name.start_with?("__")
       end
@@ -56,12 +64,24 @@ def print_type(type)
         TypeKindPrinters::STRATEGIES.fetch(type.kind).print(type)
       end
 
+      def print_directive(directive)
+        TypeKindPrinters::DirectivePrinter.print(directive)
+      end
+
       module TypeKindPrinters
-        module FieldPrinter
-          def print_fields(type)
-            type.all_fields.map{ |field| "  #{field.name}#{print_args(field)}: #{field.type}" }.join("\n")
+        module DeprecatedPrinter
+          def print_deprecated(field_or_enum_value)
+            return unless field_or_enum_value.deprecation_reason
+
+            if field_or_enum_value.deprecation_reason == ''
+              ' @deprecated'
+            else
+              " @deprecated(reason: #{field_or_enum_value.deprecation_reason.to_s.inspect})"
+            end
           end
+        end
 
+        module ArgsPrinter
           def print_args(field)
             return if field.arguments.empty?
             "(#{field.arguments.values.map{ |arg| print_input_value(arg) }.join(", ")})"
@@ -105,6 +125,24 @@ def print_value(value, type)
           end
         end
 
+        module FieldPrinter
+          include DeprecatedPrinter
+          include ArgsPrinter
+          def print_fields(type)
+            type.all_fields.map{ |field|
+              "  #{field.name}#{print_args(field)}: #{field.type}#{print_deprecated(field)}"
+            }.join("\n")
+          end
+        end
+
+        class DirectivePrinter
+          extend ArgsPrinter
+          def self.print(directive)
+            "directive @#{directive.name}#{print_args(directive)} "\
+            "on #{directive.locations.join(' | ')}"
+          end
+        end
+
         class ScalarPrinter
           def self.print(type)
             "scalar #{type.name}"
@@ -137,8 +175,9 @@ def self.print(type)
         end
 
         class EnumPrinter
+          extend DeprecatedPrinter
           def self.print(type)
-            values = type.values.values.map{ |v| "  #{v.name}" }.join("\n")
+            values = type.values.values.map{ |v| "  #{v.name}#{print_deprecated(v)}" }.join("\n")
             "enum #{type.name} {\n#{values}\n}"
           end
         end

spec/graphql/introspection/directive_type_spec.rb

@@ -42,6 +42,16 @@
             "onFragment" => true,
             "onOperation" => false,
           },
+          {
+            "name" => "deprecated",
+            "args" => [
+              {"name"=>"reason", "type"=>{"name"=>"Non-Null", "ofType"=>{"name"=>"String"}}}
+            ],
+            "locations"=>["FIELD_DEFINITION", "ENUM_VALUE"],
+            "onField" => false,
+            "onFragment" => false,
+            "onOperation" => false,
+          },
         ]
       }
     }}

spec/graphql/schema/printer_spec.rb

@@ -13,6 +13,7 @@
 
       value "FOO"
       value "BAR"
+      value "BAZ", deprecation_reason: 'Use "BAR".'
     end
 
     sub_input_type = GraphQL::InputObjectType.define do
@@ -46,6 +47,7 @@
       field :title, !types.String
       field :body, !types.String
       field :comments, types[!comment_type]
+      field :comments_count, !types.Int, deprecation_reason: 'Use "comments".'
     end
 
     query_root = GraphQL::ObjectType.define do
@@ -70,24 +72,32 @@
   query: Query
 }
 
+directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+directive @deprecated(reason: String! = \"No longer supported\") on FIELD_DEFINITION | ENUM_VALUE
+
 type __Directive {
   name: String!
   description: String
   args: [__InputValue!]!
   locations: [__DirectiveLocation!]!
-  onOperation: Boolean!
-  onFragment: Boolean!
-  onField: Boolean!
+  onOperation: Boolean! @deprecated(reason: \"Moved to 'locations' field\")
+  onFragment: Boolean! @deprecated(reason: \"Moved to 'locations' field\")
+  onField: Boolean! @deprecated(reason: \"Moved to 'locations' field\")
 }
 
 enum __DirectiveLocation {
   QUERY
   MUTATION
   SUBSCRIPTION
   FIELD
+  FIELD_DEFINITION
   FRAGMENT_DEFINITION
   FRAGMENT_SPREAD
   INLINE_FRAGMENT
+  ENUM_VALUE
 }
 
 type __EnumValue {
@@ -158,6 +168,7 @@
 enum Choice {
   FOO
   BAR
+  BAZ @deprecated(reason: "Use \\\"BAR\\\".")
 }
 
 type Comment implements Node {
@@ -173,6 +184,7 @@
   title: String!
   body: String!
   comments: [Comment!]
+  comments_count: Int! @deprecated(reason: \"Use \\\"comments\\\".\")
 }
 
 type Query {