Class: Apiwork::API::Object

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

Overview

Block context for defining reusable object types.

Accessed via ‘object :name do` in API or contract definitions. Use type methods to define params: Object#string, Object#integer, Object#decimal, Object#boolean, #array, #record, Object#object, Object#union, Object#reference.

Examples:

instance_eval style

object :item do
  string :description
  decimal :amount
end

yield style

object :item do |object|
  object.string :description
  object.decimal :amount
end

See Also:

Instance Attribute Summary

Attributes inherited from Object

#merged, #params

Instance Method Summary collapse

Methods inherited from Object

#array?, #binary, #binary?, #boolean, #boolean?, #date, #date?, #datetime, #datetime?, #decimal, #decimal?, #extends, #initialize, #integer, #integer?, #literal, #merge, #number, #number?, #object, #object?, #record?, #reference, #reference?, #string, #string?, #time, #time?, #union, #union?, #unknown, #unknown?, #uuid, #uuid?

Constructor Details

This class inherits a constructor from Apiwork::Object

Instance Method Details

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

This method returns an undefined value.

Defines an array param with element type.

Examples:

instance_eval style

array :tags do
  string
end

yield style

array :tags do |element|
  element.string
end

Parameters:

  • name (Symbol) —

    The param 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 for defining element type

Yield Parameters:

Raises:

  • (ArgumentError) 


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
193
194
195
196
 
# File 'lib/apiwork/api/object.rb', line 167

def array(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  optional: false,
  required: false,
  &block
)
  raise ArgumentError, 'array requires a block' unless block

  element = Element.new
  block.arity.positive? ? yield(element) : element.instance_eval(&block)
  element.validate!

  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    optional:,
    required:,
    of: element,
    type: :array,
  )
end

#param(name, type: nil, as: nil, custom_type: nil, default: UNSET, deprecated: false, description: nil, discriminator: nil, enum: nil, example: nil, format: nil, max: nil, min: nil, nullable: false, of: nil, optional: false, required: false, shape: nil, value: nil) {|shape| ... } ⇒ void

This method returns an undefined value.

Defines a param with explicit type.

This is the verbose form. Prefer sugar methods (string, integer, etc.) for static definitions. Use ‘param` for dynamic param generation.

Examples:

Dynamic param generation

param_type = :string
param :title, type: param_type

Object with block

param :metadata, type: :object do
  string :key
  string :value
end

Parameters:

  • name (Symbol) —

    The param name.

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

    (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :record, :string, :time, :union, :unknown, :uuid] The param type.

  • 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.

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

    (nil) The allowed values.

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

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

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

    (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :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: ‘:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`), `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).

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

    (nil) The maximum. For ‘:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.

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

    (nil) The minimum. For ‘:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.

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

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

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

    (nil) The element or value type. Arrays and records only.

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

    (false) Whether the param is optional.

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

    (false) Whether the param is required.

  • shape (API::Object, API::Union, nil) (defaults to: nil) —

    (nil) The pre-built shape.

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

    (nil) The literal value.

Yields:

  • block for nested structure

Yield Parameters:



84
85
86
87
88
89
90
91
92
93
94
95
96
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
129
130
131
132
133
 
# File 'lib/apiwork/api/object.rb', line 84

def param(
  name,
  type: nil,
  as: nil,
  custom_type: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  discriminator: nil,
  enum: nil,
  example: nil,
  format: nil,
  max: nil,
  min: nil,
  nullable: false,
  of: nil,
  optional: false,
  required: false,
  shape: nil,
  value: nil,
  &block
)
  resolved_of = resolve_of(of, type, &block)
  resolved_shape = [:array, :record].include?(type) ? nil : (shape || build_shape(type, discriminator, &block))
  discriminator = resolved_of&.discriminator if type == :array

  param_hash = {
    as:,
    custom_type:,
    deprecated:,
    description:,
    discriminator:,
    enum:,
    example:,
    format:,
    max:,
    min:,
    name:,
    nullable:,
    optional:,
    required:,
    type:,
    value:,
    of: resolved_of,
  }.compact
  param_hash[:default] = default unless UNSET.equal?(default)
  param_hash[:shape] = resolved_shape if resolved_shape

  @params[name] = (@params[name] || {}).merge(param_hash)
end

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

This method returns an undefined value.

Defines a record param with value type.

Examples:

instance_eval style

record :scores do
  integer
end

yield style

record :scores do |element|
  element.integer
end

Parameters:

  • name (Symbol) —

    The param 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 for defining value type

Yield Parameters:

Raises:

  • (ArgumentError) 


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
258
259
 
# File 'lib/apiwork/api/object.rb', line 230

def record(
  name,
  as: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  nullable: false,
  optional: false,
  required: false,
  &block
)
  raise ArgumentError, 'record requires a block' unless block

  element = Element.new
  block.arity.positive? ? yield(element) : element.instance_eval(&block)
  element.validate!

  param(
    name,
    as:,
    default:,
    deprecated:,
    description:,
    nullable:,
    optional:,
    required:,
    of: element,
    type: :record,
  )
end