Add field deprecation

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Improved error messages
 - Option to define custom derived types
 - Option to use custom keys in paginated content
+- Option to deprecate individual fields
 
 ### Fixed
 

README.md

@@ -257,7 +257,7 @@ end
 - sum types
 - api doc rendering based on export (e.g. rails engine with web ui)
 - [query logs metadata](https://github.com/rmosolgo/graphql-ruby/blob/dcaaed1cea47394fad61fceadf291ff3cb5f2932/lib/generators/graphql/install_generator.rb#L48-L52)
-- deprecation feature
+- type-level deprecation
 - maybe make `type:` optional for path params as they're always strings anyway
 - various openapi features
   - non-JSON content types (e.g. for file uploads)

lib/taro/export/open_api_v3.rb

@@ -115,23 +115,29 @@ def export_scalar_field(field)
     # as it puts props like format together with the main type.
     # https://github.com/OAI/OpenAPI-Specification/issues/3148
     base = { oneOf: [base, { type: 'null' }] } if field.null
-    base[:description] = field.desc if field.desc
-    base[:default] = field.default if field.default_specified?
-    base[:enum] = field.enum if field.enum
-    base
+    base.merge(field_metadata(field))
   end
 
   def export_complex_field_ref(field)
     ref = extract_component_ref(field.type)
+    return ref if field_metadata(field).empty? && !field.null
+
     if field.null
       # RE nullable: https://stackoverflow.com/a/70658334
-      { description: field.desc, oneOf: [ref, { type: 'null' }] }.compact
-    elsif field.desc
+      { oneOf: [ref, { type: 'null' }] }
+    else # i.e. with metadata such as description or deprecated
       # https://github.com/OAI/OpenAPI-Specification/issues/2033
-      { description: field.desc, allOf: [ref] }
-    else
-      ref
-    end
+      { allOf: [ref] }
+    end.merge(field_metadata(field))
+  end
+
+  def field_metadata(field)
+    meta = {}
+    meta[:description] = field.desc if field.desc
+    meta[:deprecated] = field.deprecated unless field.deprecated.nil?
+    meta[:default] = field.default if field.default_specified?
+    meta[:enum] = field.enum if field.enum
+    meta
   end
 
   def extract_component_ref(type)

lib/taro/types/field.rb

@@ -1,11 +1,11 @@
 require_relative 'field_validation'
 
-Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc) do
+Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc, :deprecated) do
   include Taro::Types::FieldValidation
 
-  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil)
+  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil, deprecated: nil)
     enum = coerce_to_enum(enum)
-    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:)
+    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:, deprecated:)
   end
 
   def value_for_input(object)

spec/taro/export/open_api_v3_spec.rb

@@ -1,7 +1,7 @@
 describe Taro::Export::OpenAPIv3 do
   it 'handles Declarations' do
     stub_const('FailureType', Class.new(T::ObjectType) do
-      field :message, type: 'String', null: true
+      field :message, type: 'String', null: true, deprecated: true
       field :code, type: 'Integer', null: false
     end)
 
@@ -96,6 +96,7 @@
                 oneOf:
                 - type: string
                 - type: 'null'
+                deprecated: true
               code:
                 type: integer
           Failure_List: