Class: ApiRegulator::Api

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(controller_class, action_name, desc: nil, title: nil, versions: [], tags: [], &block) ⇒ Api

Returns a new instance of Api.



6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
# File 'lib/api_regulator/api.rb', line 6

def initialize(controller_class, action_name, desc: nil, title: nil, versions: [], tags: [], &block)
  @controller_class = controller_class
  @controller_name = controller_class.name
  @controller_path = controller_class.controller_path
  @action_name = action_name.to_s
  @description = desc
  @title = title
  @tags = tags.presence || default_tags
  @versions = Array(versions).map(&:to_sym)

  @params = []
  @responses = {}

  instance_eval(&block) if block_given?
end

Instance Attribute Details

#action_name ⇒ Object (readonly)

Returns the value of attribute action_name.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def action_name
  @action_name
end

#controller_class ⇒ Object (readonly)

Returns the value of attribute controller_class.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def controller_class
  @controller_class
end

#controller_name ⇒ Object (readonly)

Returns the value of attribute controller_name.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def controller_name
  @controller_name
end

#controller_path ⇒ Object (readonly)

Returns the value of attribute controller_path.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def controller_path
  @controller_path
end

#description ⇒ Object (readonly)

Returns the value of attribute description.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def description
  @description
end

#examples ⇒ Object (readonly)

Returns the value of attribute examples.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def examples
  @examples
end

#params ⇒ Object (readonly)

Returns the value of attribute params.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def params
  @params
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def responses
  @responses
end

#tags ⇒ Object (readonly)

Returns the value of attribute tags.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def tags
  @tags
end

#title ⇒ Object (readonly)

Returns the value of attribute title.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def title
  @title
end

#versions ⇒ Object (readonly)

Returns the value of attribute versions.



3
4
5
 
# File 'lib/api_regulator/api.rb', line 3

def versions
  @versions
end

Instance Method Details

#allows_body? ⇒ Boolean

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/api_regulator/api.rb', line 108

def allows_body?
  http_method != "get"
end

#default_tags ⇒ Object 



92
93
94
95
96
97
98
99
100
 
# File 'lib/api_regulator/api.rb', line 92

def default_tags
  [
    controller_name
      .demodulize
      .sub("Controller", "")
      .underscore
      .humanize
  ]
end

#example(name, value, default: false) ⇒ Object 



61
62
63
64
65
 
# File 'lib/api_regulator/api.rb', line 61

def example(name, value, default: false)
  @examples ||= {}
  @examples[name] = { summary: "#{name} Example", value: value }
  @default_example = value if default
end

#for_version?(version) ⇒ Boolean

Returns:

  • (Boolean) 


102
103
104
105
106
 
# File 'lib/api_regulator/api.rb', line 102

def for_version?(version)
  return true unless versions.present? && version.present?

  versions.include?(version.to_sym)
end

#http_method ⇒ Object 



73
74
75
 
# File 'lib/api_regulator/api.rb', line 73

def http_method
  rails_route.verb&.downcase
end

#operation_id ⇒ Object 



88
89
90
 
# File 'lib/api_regulator/api.rb', line 88

def operation_id
  "#{controller_path.gsub("/", "-")}-#{action_name}"
end

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



22
23
24
25
 
# File 'lib/api_regulator/api.rb', line 22

def param(name, type = nil, **options, &block)
  options[:api] ||= self
  @params << Param.new(name, type, **options, &block)
end

#path ⇒ Object 



67
68
69
70
71
 
# File 'lib/api_regulator/api.rb', line 67

def path
  rails_route.path.spec.to_s
    .sub("(.:format)", "")   # Remove optional format
    .gsub(/:([\w_]+)/, '{\1}') # Replace `:param` with `{param}`
end

#rails_route ⇒ Object 



77
78
79
80
81
82
83
84
85
86
 
# File 'lib/api_regulator/api.rb', line 77

def rails_route
  route = Rails.application.routes.routes.find do |r|
    r.defaults[:controller] == controller_path &&
    r.defaults[:action] == action_name
  end

  raise "HTTP method not found for #{controller_name}##{action_name}" unless route

  route
end

#ref(ref_name, except: [], only: []) ⇒ Object 



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/api_regulator/api.rb', line 27

def ref(ref_name, except: [], only: [])
  shared_schema = ApiRegulator.shared_schema(ref_name)
  raise "Shared schema #{ref_name} not found" unless shared_schema

  # Filter parameters based on `only` or `except` options
  filtered_params = shared_schema.params

  if only.any?
    filtered_params = filtered_params.select { |param| only.include?(param.name) }
  elsif except.any?
    filtered_params = filtered_params.reject { |param| except.include?(param.name) }
  end

  filtered_params.each do |shared_param|
    @params << shared_param
  end

  shared_schema.responses.each_value { |r| r.options[:desc] ||= r.desc }
  @responses.merge!(shared_schema.responses)
end

#response(status_code, description_or_options, &block) ⇒ Object 



48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/api_regulator/api.rb', line 48

def response(status_code, description_or_options, &block)
  if description_or_options.is_a?(Hash) && description_or_options[:ref]
    # Reference to a shared schema
    resp_ref  = description_or_options[:ref]
    resp_desc = description_or_options[:desc] || resp_ref
    @responses[status_code] = Param.new(:root, :object, ref: resp_ref, desc: resp_desc, &block)
  else
    # Inline schema definition
    schema = Param.new(:root, :object, desc: description_or_options, &block)
    @responses[status_code] = schema
  end
end