Class: SwaggerYard::Operation

Inherits:
Object
  • Object
show all
Defined in:
lib/swagger_yard/operation.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path_item) ⇒ Operation

Returns a new instance of Operation.



46
47
48
49
50
51
52
53
 
# File 'lib/swagger_yard/operation.rb', line 46

def initialize(path_item)
  @path_item      = path_item
  @summary        = nil
  @description    = ""
  @parameters     = []
  @default_response = nil
  @responses = []
end

Instance Attribute Details

#description ⇒ Object

Returns the value of attribute description.



8
9
10
 
# File 'lib/swagger_yard/operation.rb', line 8

def description
  @description
end

#http_method ⇒ Object (readonly)

Returns the value of attribute http_method.



10
11
12
 
# File 'lib/swagger_yard/operation.rb', line 10

def http_method
  @http_method
end

#parameters ⇒ Object (readonly)

Returns the value of attribute parameters.



11
12
13
 
# File 'lib/swagger_yard/operation.rb', line 11

def parameters
  @parameters
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



10
11
12
 
# File 'lib/swagger_yard/operation.rb', line 10

def path
  @path
end

#path_item ⇒ Object (readonly)

Returns the value of attribute path_item.



12
13
14
 
# File 'lib/swagger_yard/operation.rb', line 12

def path_item
  @path_item
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



12
13
14
 
# File 'lib/swagger_yard/operation.rb', line 12

def responses
  @responses
end

#ruby_method ⇒ Object

Returns the value of attribute ruby_method.



8
9
10
 
# File 'lib/swagger_yard/operation.rb', line 8

def ruby_method
  @ruby_method
end

#summary ⇒ Object 



55
56
57
 
# File 'lib/swagger_yard/operation.rb', line 55

def summary
  @summary || description.split("\n\n").first || ""
end

Class Method Details

.from_yard_object(yard_object, path_item) ⇒ Object

TODO: extract to operation builder?



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/swagger_yard/operation.rb', line 15

def self.from_yard_object(yard_object, path_item)
  new(path_item).tap do |operation|
    operation.ruby_method = yard_object.name(false)
    operation.description = yard_object.docstring
    yard_object.tags.each do |tag|
      case tag.tag_name
      when "path"
        tag = SwaggerYard.requires_type(tag)
        operation.add_path_params_and_method(tag) if tag
      when "parameter"
        operation.add_parameter(tag)
      when "response_type"
        tag = SwaggerYard.requires_type(tag)
        operation.add_response_type(Type.from_type_list(tag.types), tag.text) if tag
      when "error_message", "response"
        operation.add_response(tag)
      when "summary"
        operation.summary = tag.text
      when "example"
        if tag.name && !tag.name.empty?
          operation.response(tag.name).example = tag.text
        else
          operation.default_response.example = tag.text
        end
      end
    end

    operation.sort_parameters
  end
end

Instance Method Details

#add_or_update_parameter(parameter) ⇒ Object 



121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/swagger_yard/operation.rb', line 121

def add_or_update_parameter(parameter)
  if existing = @parameters.detect {|param| param.name == parameter.name }
    existing.description    = parameter.description unless parameter.from_path?
    existing.param_type     = parameter.param_type if parameter.from_path?
    existing.required     ||= parameter.required
    existing.allow_multiple = parameter.allow_multiple
  elsif parameter.param_type == 'body' && @parameters.detect {|param| param.param_type == 'body'}
    SwaggerYard.log.warn 'multiple body parameters invalid: ' \
      "ignored #{parameter.name} for #{@path_item.api_group.class_name}##{ruby_method}"
  else
    @parameters << parameter
  end
end

#add_parameter(tag) ⇒ Object

Example: [Array] status Filter by status. (e.g. status[]=1&status=2&status[]=3) Example: [Array] status(required) Filter by status. (e.g. status[]=1&status=2&status[]=3) Example: [Array] status(required, body) Filter by status. (e.g. status[]=1&status=2&status[]=3) Example: [Integer] media ID of the desired media type.



116
117
118
119
 
# File 'lib/swagger_yard/operation.rb', line 116

def add_parameter(tag)
  param = Parameter.from_yard_tag(tag)
  add_or_update_parameter param if param
end

#add_path_params_and_method(tag) ⇒ Object

Example: [GET] /api/v2/ownerships Example: [PUT] /api/v1/accounts/account_id



96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/swagger_yard/operation.rb', line 96

def add_path_params_and_method(tag)
  if @path && @http_method
    SwaggerYard.log.warn 'multiple path tags not supported: ' \
      "ignored [#{tag.types.first}] #{tag.text}"
    return
  end

  @path = tag.text
  @http_method = tag.types.first

  parse_path_params(tag.text).each do |name|
    add_or_update_parameter Parameter.from_path_param(name)
  end
end

#add_response(tag) ⇒ Object 



160
161
162
163
164
165
166
167
 
# File 'lib/swagger_yard/operation.rb', line 160

def add_response(tag)
  tag = SwaggerYard.requires_name(tag)
  return unless tag
  r = response(tag.name)
  r.description = tag.text if tag.text
  r.type = Type.from_type_list(Array(tag.types)) if tag.types
  r
end

#add_response_type(type, desc) ⇒ Object

Example:



144
145
146
147
 
# File 'lib/swagger_yard/operation.rb', line 144

def add_response_type(type, desc)
  default_response.type = type
  default_response.description = desc
end

#api_group ⇒ Object 



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

def api_group
  path_item.api_group
end

#default_response ⇒ Object 



135
136
137
138
139
 
# File 'lib/swagger_yard/operation.rb', line 135

def default_response
  @default_response ||= Response.new.tap do |r|
    r.status = 'default'
  end
end

#extended_attributes ⇒ Object 



80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/swagger_yard/operation.rb', line 80

def extended_attributes
  {}.tap do |h|
    # Rails controller/action: if constantize/controller_path methods are
    # unavailable or constant is not defined, catch exception and skip these
    # attributes.
    begin
      h["x-controller"] = api_group.class_name.constantize.controller_path.to_s
      h["x-action"]     = ruby_method.to_s
    rescue NameError, NoMethodError
    end
  end
end

#operation_id ⇒ Object 



59
60
61
 
# File 'lib/swagger_yard/operation.rb', line 59

def operation_id
  "#{api_group.resource}-#{ruby_method}"
end

#response(name) ⇒ Object 



149
150
151
152
153
154
155
156
157
158
 
# File 'lib/swagger_yard/operation.rb', line 149

def response(name)
  status = Integer(name)
  resp = responses.detect { |r| r.status == status }
  unless resp
    resp = Response.new
    resp.status = status
    responses << resp
  end
  resp
end

#responses_by_status ⇒ Object 



71
72
73
74
75
76
77
78
 
# File 'lib/swagger_yard/operation.rb', line 71

def responses_by_status
  {}.tap do |hash|
    hash['default'] = default_response if @default_response || @responses.empty?
    responses.each do |response|
      hash[response.status] = response
    end
  end
end

#sort_parameters ⇒ Object 



169
170
171
 
# File 'lib/swagger_yard/operation.rb', line 169

def sort_parameters
  @parameters.sort_by! {|p| p.name}
end

#tags ⇒ Object 



67
68
69
 
# File 'lib/swagger_yard/operation.rb', line 67

def tags
  [api_group.resource].compact
end