Module: Rswag::Specs::ExampleGroupHelpers

Defined in:
lib/rswag/specs/example_group_helpers.rb

Instance Method Summary collapse

Instance Method Details

#description(value = nil) ⇒ Object

NOTE: ‘description’ requires special treatment because ExampleGroup already defines a method with that name. Provide an override that supports the existing functionality while also setting the appropriate metadata if applicable



31
32
33
34
35
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 31

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

  metadata[:operation][:description] = value
end

#example(mime, name, value, summary = nil, description = nil) ⇒ Object 



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 95

def example(mime, name, value, summary=nil, description=nil)
  # Todo - move initialization of metadata somewhere else.
  if metadata[:response][:content].blank?
    metadata[:response][:content] = {}
  end

  if metadata[:response][:content][mime].blank?
    metadata[:response][:content][mime] = {}
    metadata[:response][:content][mime][:examples] = {}
  end

  example_object = {
    value: value,
    summary: summary,
    description: description
  }.select { |_, v| v.present? }
  # TODO, issue a warning if example is being overridden with the same key
  metadata[:response][:content][mime][:examples].merge!(
    { name.to_sym => example_object }
  )
end

#examples(examples = nil) ⇒ Object

NOTE: Similar to ‘description’, ‘examples’ need to handle the case when being invoked with no params to avoid overriding ‘examples’ method of rspec-core ExampleGroup



87
88
89
90
91
92
93
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 87

def examples(examples = nil)
  return super() if examples.nil?
  # should we add a deprecation warning?
  examples.each_with_index do |(mime, example_object), index|
    example(mime, "example_#{index}", example_object)
  end
end

#header(name, attributes) ⇒ Object 



78
79
80
81
82
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 78

def header(name, attributes)
  metadata[:response][:headers] ||= {}

  metadata[:response][:headers][name] = attributes
end

#parameter(attributes) ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 44

def parameter(attributes)
  if attributes[:in] && attributes[:in].to_sym == :path
    attributes[:required] = true
  end

  if metadata.key?(:operation)
    metadata[:operation][:parameters] ||= []
    metadata[:operation][:parameters] << attributes
  else
    metadata[:path_item][:parameters] ||= []
    metadata[:path_item][:parameters] << attributes
  end
end

#path(template, metadata = {}, &block) ⇒ Object 



10
11
12
13
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 10

def path(template, metadata = {}, &block)
  metadata[:path_item] = { template: template }
  describe(template, metadata, &block)
end

#request_body_example(value:, summary: nil, name: nil) ⇒ Object 



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 58

def request_body_example(value:, summary: nil, name: nil)
  if metadata.key?(:operation)
    metadata[:operation][:request_examples] ||= []
    example = { value: value }
    example[:summary] = summary if summary
    # We need the examples to have a unique name for a set of examples, so just make the name the length if one isn't provided.
    example[:name] = name || metadata[:operation][:request_examples].length()
    metadata[:operation][:request_examples] << example
  end
end

#response(code, description, metadata = {}, &block) ⇒ Object 



69
70
71
72
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 69

def response(code, description, metadata = {}, &block)
  metadata[:response] = { code: code, description: description }
  context(description, metadata, &block)
end

#run_test!(description = nil, *args, **options, &block) ⇒ void

This method returns an undefined value.

Perform request and assert response matches swagger definitions

Parameters:

  • description (String) (defaults to: nil) —

    description of the test

  • args (Array) —

    arguments to pass to the ‘it` method

  • options (Hash) —

    options to pass to the ‘it` method

  • &block (Proc) —

    you can make additional assertions within that block



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 125

def run_test!(description = nil, *args, **options, &block)
  # rswag metadata value defaults to true
  options[:rswag] = true unless options.key?(:rswag)

  description ||= "returns a #{metadata[:response][:code]} response"

  if RSPEC_VERSION < 3
    ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: Support for RSpec 2.X will be dropped in v3.0')
    before do
      submit_request(example.metadata)
    end

    it description, *args, **options do
      assert_response_matches_metadata(metadata)
      block.call(response) if block_given?
    end
  else
    before do |example|
      submit_request(example.metadata)
    end

    it description, *args, **options do |example|
      assert_response_matches_metadata(example.metadata, &block)
      example.instance_exec(response, &block) if block_given?
    end
  end
end

#schema(value) ⇒ Object 



74
75
76
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 74

def schema(value)
  metadata[:response][:schema] = value
end