Module: Scorpio::OpenAPI::Operation

Includes:
Document::Descendent, Configurables
Included in:
Google::RestMethod, V2Methods, V3Methods
Defined in:
lib/scorpio/openapi/operation.rb,
lib/scorpio/openapi/operation.rb,
lib/scorpio/openapi/operation.rb

Overview

An OpenAPI operation

Scorpio::OpenAPI::Operation is a module common to V2 and V3 operations.

Defined Under Namespace

Modules: Configurables, V2Methods, V3Methods

Instance Attribute Summary

Attributes included from Configurables

#accept, #authorization, #base_url, #faraday_adapter, #faraday_builder, #logger, #request_headers, #user_agent

Instance Method Summary collapse

Methods included from Document::Descendent

#openapi_document

Instance Method Details

#build_request(**configuration, &b) ⇒ Scorpio::Request

instantiates a Request for this operation. configuration is passed to Request#initialize.

Returns:



202
203
204
 
# File 'lib/scorpio/openapi/operation.rb', line 202

def build_request(**configuration, &b)
  Scorpio::Request.new(self, **configuration, &b)
end

#delete? ⇒ Boolean

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/scorpio/openapi/operation.rb', line 121

def delete?
  'delete'.casecmp?(http_method)
end

#each_link_page(**configuration) {|Scorpio::Ur| ... } ⇒ Enumerator?

Runs this operation with the given request config, and yields the resulting Ur. If the response contains a Link header with a next link, this operation is run again to that link's URL, that request's Ur yielded, and a next link in that response is followed. This repeats until a response does not contain a Link header with a next link.

Parameters:

  • configuration (#to_hash) —

    A hash of configurable attributes or parameters for the request - instance methods of Request::Configurables, or request parameters defined by the operation.

Yields:

Returns:

  • (Enumerator, nil) 


228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/scorpio/openapi/operation.rb', line 228

def each_link_page(**configuration, &block)
  init_request = build_request(**configuration)
  next_page = proc do |last_page_ur|
    nextlinks = last_page_ur.response.links.select { |link| link.rel?('next') }
    if nextlinks.size == 0
      # no next link; we are at the end
      nil
    elsif nextlinks.size == 1
      run_ur(**configuration, url: nextlinks.first.absolute_target_uri)
    else
      # TODO better error class / context / message
      raise("response included multiple links with rel=next")
    end
  end
  init_request.each_page_ur(next_page: next_page, &block)
end

#get? ⇒ Boolean

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/scorpio/openapi/operation.rb', line 109

def get?
  'get'.casecmp?(http_method)
end

#head? ⇒ Boolean

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/scorpio/openapi/operation.rb', line 129

def head?
  'head'.casecmp?(http_method)
end

#http_method ⇒ String

the HTTP method of this operation as indicated by the attribute name for this operation from the parent PathItem

Returns:

  • (String) 


103
104
105
106
107
 
# File 'lib/scorpio/openapi/operation.rb', line 103

def http_method
  return @http_method if instance_variable_defined?(:@http_method)
  return(@http_method = nil) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::PathItem)
  @http_method = jsi_ptr.tokens.last
end

#human_id ⇒ String

a short identifier for this operation appropriate for an error message

Returns:

  • (String) 


149
150
151
 
# File 'lib/scorpio/openapi/operation.rb', line 149

def human_id
  operationId || -"path: #{path_template_str}, method: #{http_method}"
end

#inferred_parameters ⇒ #to_ary<#to_hash>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

the parameters specified for this operation, plus any others scorpio considers to be parameters.

Returns:

  • (#to_ary<#to_hash>) 


182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/scorpio/openapi/operation.rb', line 182

def inferred_parameters
  parameters = inherited_parameters.dup
  path_template.variables.each do |var|
    unless parameters.any? { |p| p['in'] == 'path' && p['name'] == var }
      # we could instantiate this as a V2::Parameter or a V3_0::Parameter
      # or a ParameterWithContentInPath or whatever. but I can't be bothered.
      parameters << {
        'name' => var,
        'in' => 'path',
        'required' => true,
        'type' => 'string',
      }
    end
  end
  parameters.freeze
end

#inherited_parameters ⇒ #to_ary<#to_hash>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

operation parameters + path item parameters

Returns:

  • (#to_ary<#to_hash>) 


168
169
170
171
172
173
174
175
176
 
# File 'lib/scorpio/openapi/operation.rb', line 168

def inherited_parameters
  parameters = []
  parameters.concat(self.parameters.to_ary) if self.parameters
  path_item = jsi_ancestor_nodes.detect { |n| n.is_a?(OpenAPI::PathItem) }
  parameters.concat((path_item && path_item.parameters || []).select do |pip|
    parameters.none? { |p| p['in'] == pip['in'] && p['name'] == pip['name'] }
  end)
  parameters.freeze
end

#oa_response(status:) ⇒ OpenAPI::Response?

Parameters:

  • status (String, Integer)

Returns:



155
156
157
158
159
160
161
162
 
# File 'lib/scorpio/openapi/operation.rb', line 155

def oa_response(status: )
  return nil if !responses
  status = status.to_s if status.is_a?(Numeric)
  responses.each do |k, v|
    return v if k.to_s == status
  end
  responses[-"#{status[0]}XX"] || responses['default']
end

#options? ⇒ Boolean

Returns:

  • (Boolean) 


125
126
127
 
# File 'lib/scorpio/openapi/operation.rb', line 125

def options?
  'options'.casecmp?(http_method)
end

#patch? ⇒ Boolean

Returns:

  • (Boolean) 


133
134
135
 
# File 'lib/scorpio/openapi/operation.rb', line 133

def patch?
  'patch'.casecmp?(http_method)
end

#path_template ⇒ Addressable::Template

the path as an Addressable::Template

Returns:

  • (Addressable::Template) 


82
83
84
85
86
 
# File 'lib/scorpio/openapi/operation.rb', line 82

def path_template
  return @path_template if instance_variable_defined?(:@path_template)
  return(@path_template = nil) if !path_template_str
  @path_template = Addressable::Template.new(path_template_str)
end

#path_template_str ⇒ String

Returns:

  • (String) 


74
75
76
77
78
 
# File 'lib/scorpio/openapi/operation.rb', line 74

def path_template_str
  return @path_template_str if instance_variable_defined?(:@path_template_str)
  path_item = jsi_ancestor_nodes.detect { |n| n.is_a?(Scorpio::OpenAPI::PathItem) }
  @path_template_str = path_item && path_item.jsi_ptr.tokens.last
end

#post? ⇒ Boolean

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/scorpio/openapi/operation.rb', line 117

def post?
  'post'.casecmp?(http_method)
end

#put? ⇒ Boolean

Returns:

  • (Boolean) 


113
114
115
 
# File 'lib/scorpio/openapi/operation.rb', line 113

def put?
  'put'.casecmp?(http_method)
end

#run(mutable: false, **configuration, &b) ⇒ Object

runs a Request for this operation - see Request#run. configuration is passed to Request#initialize.

Returns:

  • response body object



216
217
218
 
# File 'lib/scorpio/openapi/operation.rb', line 216

def run(mutable: false, **configuration, &b)
  build_request(**configuration, &b).run(mutable: mutable)
end

#run_ur(**configuration, &b) ⇒ Scorpio::Ur

runs a Request for this operation, returning a Ur. configuration is passed to Request#initialize.

Returns:



209
210
211
 
# File 'lib/scorpio/openapi/operation.rb', line 209

def run_ur(**configuration, &b)
  build_request(**configuration, &b).run_ur
end

#tagged?(tag_name) ⇒ Boolean

Parameters:

  • tag_name (String)

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/scorpio/openapi/operation.rb', line 143

def tagged?(tag_name)
  tags.respond_to?(:to_ary) && tags.include?(tag_name)
end

#trace? ⇒ Boolean

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/scorpio/openapi/operation.rb', line 137

def trace?
  'trace'.casecmp?(http_method)
end

#uri_template(base_url: self.base_url) ⇒ Addressable::Template

the URI template, consisting of the base_url concatenated with the path template

Parameters:

  • base_url (#to_str) (defaults to: self.base_url) —

    the base URL to which the path template is appended

Returns:

  • (Addressable::Template) 


91
92
93
94
95
96
97
98
 
# File 'lib/scorpio/openapi/operation.rb', line 91

def uri_template(base_url: self.base_url)
  unless base_url
    raise(ArgumentError, -"no base_url has been specified for operation #{self}")
  end
  # we do not use Addressable::URI#join as the paths should just be concatenated, not resolved.
  # we use File.join just to deal with consecutive slashes.
  Addressable::Template.new(File.join(base_url, path_template_str))
end

#v2? ⇒ Boolean

openapi v2?

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/scorpio/openapi/operation.rb', line 69

def v2?
  is_a?(OpenAPI::V2::Operation)
end

#v3? ⇒ Boolean

openapi v3?

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/scorpio/openapi/operation.rb', line 63

def v3?
  is_a?(OpenAPI::Operation::V3Methods)
end