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



29
30
31
32
33
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 29

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

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

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



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

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



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

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 



76
77
78
79
80
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 76

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

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

#parameter(attributes) ⇒ Object 



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

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 



8
9
10
11
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 8

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

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



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

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 



67
68
69
70
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 67

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



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

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
    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 



72
73
74
 
# File 'lib/rswag/specs/example_group_helpers.rb', line 72

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