Class: Apiwork::Contract::Action

Inherits:
Object
  • Object
show all
Defined in:
lib/apiwork/contract/action.rb,
lib/apiwork/contract/action/request.rb,
lib/apiwork/contract/action/response.rb

Overview

Defines request/response structure for an action.

Returns Request via ‘request` and Response via `response`.

Defined Under Namespace

Classes: Request, Response

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(contract_class, name, replace: false) ⇒ Action

Returns a new instance of Action.



13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/apiwork/contract/action.rb', line 13

def initialize(contract_class, name, replace: false)
  @name = name
  @contract_class = contract_class
  @reset_request = replace
  @reset_response = replace
  @request = nil
  @response = nil
  @raises = []
  @summary = nil
  @description = nil
  @tags = nil
  @deprecated = nil
  @operation_id = nil
end

Instance Attribute Details

#contract_class ⇒ Object (readonly) 



10
11
12
 
# File 'lib/apiwork/contract/action.rb', line 10

def contract_class
  @contract_class
end

#name ⇒ Object (readonly) 



10
11
12
 
# File 'lib/apiwork/contract/action.rb', line 10

def name
  @name
end

Instance Method Details

#deprecated! ⇒ void

This method returns an undefined value.

Marks this action as deprecated.

Examples:

action :legacy_create do
  deprecated!
end


94
95
96
 
# File 'lib/apiwork/contract/action.rb', line 94

def deprecated!
  @deprecated = true
end

#deprecated? ⇒ Boolean

Whether this action is deprecated.

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/apiwork/contract/action.rb', line 102

def deprecated?
  @deprecated == true
end

#description(value = nil) ⇒ String?

The description for this action.

Used in generated specs as the operation description. Supports Markdown formatting.

Examples:

action :create do
  description 'Creates a new invoice and sends notification email.'
end

Parameters:

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

    (nil) The description.

Returns:

  • (String, nil) 


61
62
63
64
65
 
# File 'lib/apiwork/contract/action.rb', line 61

def description(value = nil)
  return @description if value.nil?

  @description = value
end

#operation_id(value = nil) ⇒ String?

The operation ID for this action.

Examples:

action :create do
  operation_id 'createNewInvoice'
end

Parameters:

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

    (nil) The operation ID.

Returns:

  • (String, nil) 


117
118
119
120
121
 
# File 'lib/apiwork/contract/action.rb', line 117

def operation_id(value = nil)
  return @operation_id if value.nil?

  @operation_id = value
end

#raises(*error_code_keys) ⇒ void

This method returns an undefined value.

Declares the raised error codes for this action.

Examples:

raises :not_found
raises :forbidden
action :show do
  raises :not_found, :forbidden
end

Parameters:

  • error_code_keys (Symbol) —

    The error code keys.

Raises:



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/apiwork/contract/action.rb', line 139

def raises(*error_code_keys)
  error_code_keys = error_code_keys.flatten
  error_code_keys.each do |error_code_key|
    unless error_code_key.is_a?(Symbol)
      hint = error_code_key.is_a?(Integer) ? " Use :#{ErrorCode.key_for_status(error_code_key)} instead." : ''
      raise ConfigurationError, "raises must be symbols, got #{error_code_key.class}: #{error_code_key}.#{hint}"
    end

    next if ErrorCode.exists?(error_code_key)

    raise ConfigurationError,
          "Unknown error code :#{error_code_key}. Register it with: " \
          "Apiwork::ErrorCode.register :#{error_code_key}, status: <status>"
  end
  @raises |= error_code_keys
end

#request(replace: false) {|request| ... } ⇒ Action::Request

Defines the request structure for this action.

Use the block to define query parameters and request body.

Examples:

instance_eval style

action :create do
  request do
    query do
      boolean? :dry_run
    end
    body do
      string :title
    end
  end
end

yield style

action :create do
  request do |request|
    request.query do |query|
      query.boolean? :dry_run
    end
    request.body do |body|
      body.string :title
    end
  end
end

Parameters:

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

    (false) Whether to replace inherited definition.

Yields:

  • block for defining query and body (instance_eval style)

Yield Parameters:

Returns:



190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/apiwork/contract/action.rb', line 190

def request(replace: false, &block)
  @reset_request = replace if replace

  @request ||= Request.new(contract_class, name)

  if block
    block.arity.positive? ? yield(@request) : @request.instance_eval(&block)
  end

  @request
end

#resets_request? ⇒ Boolean

Returns:

  • (Boolean) 


249
250
251
 
# File 'lib/apiwork/contract/action.rb', line 249

def resets_request?
  @reset_request
end

#resets_response? ⇒ Boolean

Returns:

  • (Boolean) 


253
254
255
 
# File 'lib/apiwork/contract/action.rb', line 253

def resets_response?
  @reset_response
end

#response(replace: false) {|response| ... } ⇒ Action::Response

Defines the response structure for this action.

Use the block to define response body or declare no_content.

Examples:

instance_eval style

action :show do
  response do
    body do
      uuid :id
      string :title
    end
  end
end

yield style

action :show do
  response do |response|
    response.body do |body|
      body.uuid :id
      body.string :title
    end
  end
end

No content response

action :destroy do
  response { no_content! }
end

Parameters:

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

    (false) Whether to replace inherited definition.

Yields:

  • block for defining body or no_content (instance_eval style)

Yield Parameters:

Returns:



237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/apiwork/contract/action.rb', line 237

def response(replace: false, &block)
  @reset_response = replace if replace

  @response ||= Response.new(contract_class, name)

  if block
    block.arity.positive? ? yield(@response) : @response.instance_eval(&block)
  end

  @response
end

#summary(value = nil) ⇒ String?

The summary for this action.

Used in generated specs as the operation summary.

Examples:

action :create do
  summary 'Create a new invoice'
end

Parameters:

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

    (nil) The summary.

Returns:

  • (String, nil) 


41
42
43
44
45
 
# File 'lib/apiwork/contract/action.rb', line 41

def summary(value = nil)
  return @summary if value.nil?

  @summary = value
end

#tags(*tags) ⇒ Array<Symbol>?

The tags for this action.

Tags help organize actions in generated documentation.

Examples:

action :create do
  tags :billing, :invoices
end

Parameters:

  • tags (Array<String, Symbol>) —

    The tag names.

Returns:

  • (Array<Symbol>, nil) 


80
81
82
83
 
# File 'lib/apiwork/contract/action.rb', line 80

def tags(*tags)
  @tags = tags.flatten if tags.any?
  @tags
end