Class: Apiwork::Object

Inherits:
Object
  • Object
show all
Defined in:
lib/apiwork/object.rb

Direct Known Subclasses

API::Object, Contract::Object

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object

Returns a new instance of Object.



8
9
10
11
12
 
# File 'lib/apiwork/object.rb', line 8

def initialize
  @extends = []
  @merged = []
  @params = {}
end

Instance Attribute Details

#merged ⇒ Object (readonly)

Returns the value of attribute merged.



5
6
7
 
# File 'lib/apiwork/object.rb', line 5

def merged
  @merged
end

#params ⇒ Object (readonly)

Returns the value of attribute params.



5
6
7
 
# File 'lib/apiwork/object.rb', line 5

def params
  @params
end

Instance Method Details

#array(name, as: nil, default: UNSET, deprecated: false, description: nil, max: nil, min: nil, nullable: false, of: nil, optional: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines an array.

Examples:

Array of strings

array :tags do
  string
end

Array of objects

array :items do
  object do
    string :name
    decimal :price
  end
end

Array of discriminated union

array :notifications do
  union discriminator: :type do
    variant tag: 'email' do
      object do
        string :address
      end
    end
    variant tag: 'sms' do
      object do
        string :phone
      end
    end
  end
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • max (Integer, nil) (defaults to: nil) —

    (nil) The maximum number of elements.

  • min (Integer, nil) (defaults to: nil) —

    (nil) The minimum number of elements.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • of (Symbol, Hash, nil) (defaults to: nil) —

    (nil) The element type. Arrays only.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining element type



1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
 
# File 'lib/apiwork/object.rb', line 1387

def array(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  max: nil,
  min: nil,
  nullable: false,
  of: nil,
  optional: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    max:,
    min:,
    nullable:,
    of:,
    optional:,
    required:,
    type: :array,
    &block
  )
end

#array?(name, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, of: nil, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines an optional array.

Examples:

Optional array of labels

array? :labels do
  string
end

Optional array of discriminated union

array? :items do
  union discriminator: :type do
    variant tag: 'text' do
      object do
        string :content
      end
    end
    variant tag: 'image' do
      object do
        string :url
      end
    end
  end
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • of (Symbol, Hash, nil) (defaults to: nil) —

    (nil) The element type. Arrays only.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining element type



1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
 
# File 'lib/apiwork/object.rb', line 1460

def array?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  of: nil,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    of:,
    required:,
    optional: true,
    type: :array,
    &block
  )
end

#binary(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a binary.

Examples:

File content

binary :content

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
 
# File 'lib/apiwork/object.rb', line 1060

def binary(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :binary,
  )
end

#binary?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional binary.

Examples:

Optional attachment

binary? :attachment

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
 
# File 'lib/apiwork/object.rb', line 1108

def binary?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :binary,
  )
end

#boolean(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a boolean.

Examples:

Active flag

boolean :active

With default

boolean :published, default: false

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Boolean, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
 
# File 'lib/apiwork/object.rb', line 575

def boolean(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :boolean,
  )
end

#boolean?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional boolean.

Examples:

Optional notification flag

boolean? :notify, default: true

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Boolean, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
 
# File 'lib/apiwork/object.rb', line 623

def boolean?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :boolean,
  )
end

#date(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a date.

Examples:

Birth date

date :birth_date

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
 
# File 'lib/apiwork/object.rb', line 769

def date(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :date,
  )
end

#date?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional date.

Examples:

Optional expiry date

date? :expires_on

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
 
# File 'lib/apiwork/object.rb', line 817

def date?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :date,
  )
end

#datetime(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a datetime.

Examples:

Timestamp

datetime :created_at

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
 
# File 'lib/apiwork/object.rb', line 672

def datetime(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :datetime,
  )
end

#datetime?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional datetime.

Examples:

Optional deletion timestamp

datetime? :deleted_at

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
 
# File 'lib/apiwork/object.rb', line 720

def datetime?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :datetime,
  )
end

#decimal(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, max: nil, min: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a decimal.

Examples:

Price with minimum

decimal :amount, min: 0

Percentage with range

decimal :discount, min: 0, max: 100

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Numeric, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • max (Numeric, nil) (defaults to: nil) —

    (nil) The maximum value.

  • min (Numeric, nil) (defaults to: nil) —

    (nil) The minimum value.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
 
# File 'lib/apiwork/object.rb', line 350

def decimal(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  max: nil,
  min: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    max:,
    min:,
    nullable:,
    optional:,
    required:,
    type: :decimal,
  )
end

#decimal?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, max: nil, min: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional decimal.

Examples:

Optional tax rate

decimal? :tax_rate, min: 0, max: 1

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Numeric, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • max (Numeric, nil) (defaults to: nil) —

    (nil) The maximum value.

  • min (Numeric, nil) (defaults to: nil) —

    (nil) The minimum value.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'lib/apiwork/object.rb', line 406

def decimal?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  max: nil,
  min: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    max:,
    min:,
    nullable:,
    required:,
    optional: true,
    type: :decimal,
  )
end

#extends(type_name = nil) ⇒ Array<Symbol>

Inherits all properties from another type. Can be called multiple times to inherit from multiple types.

Examples:

Single inheritance

object :admin do
  extends :user
  boolean :superuser
end

Multiple inheritance

object :employee do
  extends :person
  extends :contactable
  string :employee_id
end

Parameters:

  • type_name (Symbol, nil) (defaults to: nil) —

    (nil) The type to inherit from.

Returns:

  • (Array<Symbol>) 


34
35
36
37
 
# File 'lib/apiwork/object.rb', line 34

def extends(type_name = nil)
  @extends << type_name if type_name
  @extends
end

#integer(name, as: nil, default: UNSET, deprecated: false, description: nil, enum: nil, example: nil, max: nil, min: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines an integer.

Examples:

Basic integer

integer :quantity

With range constraints

integer :age, min: 0, max: 150

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • enum (Array, Symbol, nil) (defaults to: nil) —

    (nil) The allowed values.

  • example (Integer, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • max (Integer, nil) (defaults to: nil) —

    (nil) The maximum value.

  • min (Integer, nil) (defaults to: nil) —

    (nil) The minimum value.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/apiwork/object.rb', line 228

def integer(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  enum: nil,
  example: nil,
  max: nil,
  min: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    enum:,
    example:,
    max:,
    min:,
    nullable:,
    optional:,
    required:,
    type: :integer,
  )
end

#integer?(name, as: nil, default: UNSET, deprecated: false, description: nil, enum: nil, example: nil, max: nil, min: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional integer.

Examples:

Optional page number

integer? :page, min: 1, default: 1

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • enum (Array, Symbol, nil) (defaults to: nil) —

    (nil) The allowed values.

  • example (Integer, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • max (Integer, nil) (defaults to: nil) —

    (nil) The maximum value.

  • min (Integer, nil) (defaults to: nil) —

    (nil) The minimum value.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/apiwork/object.rb', line 288

def integer?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  enum: nil,
  example: nil,
  max: nil,
  min: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    enum:,
    example:,
    max:,
    min:,
    nullable:,
    required:,
    optional: true,
    type: :integer,
  )
end

#literal(name, value:, as: nil, default: UNSET, deprecated: false, description: nil, optional: false) ⇒ void

This method returns an undefined value.

Defines a literal value.

Examples:

Fixed version number

literal :version, value: '1.0'

Parameters:

  • name (Symbol) —

    The name.

  • value (Object) —

    The exact value.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.



1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
 
# File 'lib/apiwork/object.rb', line 1739

def literal(
  name,
  value:,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  optional: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    optional:,
    value:,
    type: :literal,
  )
end

#merge(type_name = nil) ⇒ Array<Symbol>

Includes all properties from another type. Can be called multiple times to merge from multiple types.

Examples:

object :admin do
  merge :user
  boolean :superuser
end

Parameters:

  • type_name (Symbol, nil) (defaults to: nil) —

    (nil) The type to merge from.

Returns:

  • (Array<Symbol>) 


52
53
54
55
 
# File 'lib/apiwork/object.rb', line 52

def merge(type_name = nil)
  @merged << type_name if type_name
  @merged
end

#number(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, max: nil, min: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a number.

Examples:

Coordinate value

number :latitude, min: -90, max: 90

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Numeric, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • max (Numeric, nil) (defaults to: nil) —

    (nil) The maximum value.

  • min (Numeric, nil) (defaults to: nil) —

    (nil) The minimum value.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
 
# File 'lib/apiwork/object.rb', line 463

def number(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  max: nil,
  min: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    max:,
    min:,
    nullable:,
    optional:,
    required:,
    type: :number,
  )
end

#number?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, max: nil, min: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional number.

Examples:

Optional score

number? :score, min: 0, max: 100

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Numeric, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • max (Numeric, nil) (defaults to: nil) —

    (nil) The maximum value.

  • min (Numeric, nil) (defaults to: nil) —

    (nil) The minimum value.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'lib/apiwork/object.rb', line 519

def number?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  max: nil,
  min: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    max:,
    min:,
    nullable:,
    required:,
    optional: true,
    type: :number,
  )
end

#object(name, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, optional: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines an object.

Examples:

Nested address object

object :address do
  string :street
  string :city
  string :country
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining nested structure



1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
 
# File 'lib/apiwork/object.rb', line 1257

def object(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  optional: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    optional:,
    required:,
    type: :object,
    &block
  )
end

#object?(name, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines an optional object.

Examples:

Optional metadata

object? :metadata do
  string :key
  string :value
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining nested structure



1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
 
# File 'lib/apiwork/object.rb', line 1307

def object?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    required:,
    optional: true,
    type: :object,
    &block
  )
end

#param(name, type: nil, **options, &block) ⇒ Object

Raises:

  • (NotImplementedError) 


1864
1865
1866
 
# File 'lib/apiwork/object.rb', line 1864

def param(name, type: nil, **options, &block)
  raise NotImplementedError, "#{self.class} must implement #param"
end

#record(name, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, optional: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines a record.

Examples:

Record of integers

record :scores do
  integer
end

Record of objects

record :settings do
  object do
    string :value
    boolean :enabled
  end
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining value type



1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
 
# File 'lib/apiwork/object.rb', line 1520

def record(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  optional: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    optional:,
    required:,
    type: :record,
    &block
  )
end

#record?(name, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines an optional record.

Examples:

Optional record

record? :metadata do
  string
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining value type



1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
 
# File 'lib/apiwork/object.rb', line 1569

def record?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    required:,
    optional: true,
    type: :record,
    &block
  )
end

#reference(name, to: nil, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a reference to a named type.

Examples:

Reference to customer type

reference :customer

Reference with different param name

reference :billing_address, to: :address

Parameters:

  • name (Symbol) —

    The name.

  • to (Symbol, nil) (defaults to: nil) —

    (nil) The target type name. Defaults to name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
 
# File 'lib/apiwork/object.rb', line 1788

def reference(
  name,
  to: nil,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  optional: false,
  required: false
)
  reference_type = to || name

  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    optional:,
    required:,
    custom_type: reference_type,
    type: reference_type,
  )
end

#reference?(name, to: nil, as: nil, default: UNSET, deprecated: false, description: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional reference to a named type.

Examples:

Optional shipping address

reference? :shipping_address, to: :address

Parameters:

  • name (Symbol) —

    The name.

  • to (Symbol, nil) (defaults to: nil) —

    (nil) The target type name. Defaults to name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
 
# File 'lib/apiwork/object.rb', line 1838

def reference?(
  name,
  to: nil,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  required: false
)
  reference_type = to || name

  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    required:,
    custom_type: reference_type,
    optional: true,
    type: reference_type,
  )
end

#string(name, as: nil, default: UNSET, deprecated: false, description: nil, enum: nil, example: nil, format: nil, max: nil, min: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a string.

Examples:

Basic string

string :name

With format validation

string :email, format: :email

With length constraints

string :title, min: 1, max: 100

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • enum (Array, Symbol, nil) (defaults to: nil) —

    (nil) The allowed values.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • format (Symbol, nil) (defaults to: nil) —

    (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :text, :url, :uuid] Format hint for exports. Does not change the type, but exports may add validation or documentation based on it. Valid formats by type: ‘:string`.

  • max (Integer, nil) (defaults to: nil) —

    (nil) The maximum length.

  • min (Integer, nil) (defaults to: nil) —

    (nil) The minimum length.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/apiwork/object.rb', line 97

def string(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  enum: nil,
  example: nil,
  format: nil,
  max: nil,
  min: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    enum:,
    example:,
    format:,
    max:,
    min:,
    nullable:,
    optional:,
    required:,
    type: :string,
  )
end

#string?(name, as: nil, default: UNSET, deprecated: false, description: nil, enum: nil, example: nil, format: nil, max: nil, min: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional string.

Examples:

Optional string with default

string? :nickname, default: 'Anonymous'

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • enum (Array, Symbol, nil) (defaults to: nil) —

    (nil) The allowed values.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • format (Symbol, nil) (defaults to: nil) —

    (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :text, :url, :uuid] Format hint for exports. Does not change the type, but exports may add validation or documentation based on it. Valid formats by type: ‘:string`.

  • max (Integer, nil) (defaults to: nil) —

    (nil) The maximum length.

  • min (Integer, nil) (defaults to: nil) —

    (nil) The minimum length.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/apiwork/object.rb', line 162

def string?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  enum: nil,
  example: nil,
  format: nil,
  max: nil,
  min: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    enum:,
    example:,
    format:,
    max:,
    min:,
    nullable:,
    required:,
    optional: true,
    type: :string,
  )
end

#time(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a time.

Examples:

Opening time

time :opens_at

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
 
# File 'lib/apiwork/object.rb', line 963

def time(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :time,
  )
end

#time?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional time.

Examples:

Optional closing time

time? :closes_at

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
 
# File 'lib/apiwork/object.rb', line 1011

def time?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :time,
  )
end

#union(name, as: nil, default: UNSET, deprecated: false, description: nil, discriminator: nil, nullable: false, optional: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines a union.

Examples:

Payment method union

union :payment_method, discriminator: :type do
  variant tag: 'card' do
    object do
      string :last_four
    end
  end
  variant tag: 'bank' do
    object do
      string :account_number
    end
  end
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • discriminator (Symbol, nil) (defaults to: nil) —

    (nil) The discriminator field name. Unions only.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining union variants



1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
 
# File 'lib/apiwork/object.rb', line 1630

def union(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  discriminator: nil,
  nullable: false,
  optional: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    discriminator:,
    nullable:,
    optional:,
    required:,
    type: :union,
    &block
  )
end

#union?(name, as: nil, default: UNSET, deprecated: false, description: nil, discriminator: nil, nullable: false, required: false) { ... } ⇒ void

This method returns an undefined value.

Defines an optional union.

Examples:

Optional notification preference

union? :notification, discriminator: :type do
  variant tag: 'email' do
    object do
      string :address
    end
  end
  variant tag: 'sms' do
    object do
      string :phone
    end
  end
end

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • discriminator (Symbol, nil) (defaults to: nil) —

    (nil) The discriminator field name. Unions only.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.

Yields:

  • block defining union variants



1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
 
# File 'lib/apiwork/object.rb', line 1692

def union?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  discriminator: nil,
  nullable: false,
  required: false,
  &block
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    discriminator:,
    nullable:,
    required:,
    optional: true,
    type: :union,
    &block
  )
end

#unknown(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines an unknown.

Examples:

Opaque metadata

unknown :metadata

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Object, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
 
# File 'lib/apiwork/object.rb', line 1157

def unknown(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :unknown,
  )
end

#unknown?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional unknown.

Examples:

Optional metadata

unknown? :metadata

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (Object, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
 
# File 'lib/apiwork/object.rb', line 1205

def unknown?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :unknown,
  )
end

#uuid(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, optional: false, required: false) ⇒ void

This method returns an undefined value.

Defines a UUID.

Examples:

Primary key

uuid :id

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • optional (Boolean) (defaults to: false) —

    (false) Whether the param is optional.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
 
# File 'lib/apiwork/object.rb', line 866

def uuid(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  optional: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    optional:,
    required:,
    type: :uuid,
  )
end

#uuid?(name, as: nil, default: UNSET, deprecated: false, description: nil, example: nil, nullable: false, required: false) ⇒ void

This method returns an undefined value.

Defines an optional UUID.

Examples:

Optional parent reference

uuid? :parent_id

Parameters:

  • name (Symbol) —

    The name.

  • as (Symbol, nil) (defaults to: nil) —

    (nil) The target attribute name.

  • default (Object) (defaults to: UNSET) —

    (UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default.

  • deprecated (Boolean) (defaults to: false) —

    (false) Whether deprecated. Metadata included in exports.

  • description (String, nil) (defaults to: nil) —

    (nil) The description. Metadata included in exports.

  • example (String, nil) (defaults to: nil) —

    (nil) The example value. Metadata included in exports.

  • nullable (Boolean) (defaults to: false) —

    (false) Whether the value can be ‘null`.

  • required (Boolean) (defaults to: false) —

    (false) Whether the param is required.



914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
 
# File 'lib/apiwork/object.rb', line 914

def uuid?(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  example: nil,
  nullable: false,
  required: false
)
  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    example:,
    nullable:,
    required:,
    optional: true,
    type: :uuid,
  )
end