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 



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

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



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

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 



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

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 



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

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 



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

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

#run_test!(**options, &block) ⇒ void

This method returns an undefined value.

Perform request and assert response matches swagger definitions

Parameters:

  • options (Hash) —

    options to pass to the ‘it` method

  • &block (Proc) —

    you can make additional assertions within that block



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

def run_test!(**options, &block)
  options[:rswag] = true unless options.key?(:rswag)

  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 "returns a #{metadata[:response][:code]} response", **options do
      assert_response_matches_metadata(metadata)
      block.call(response) if block_given?
    end
  else
    before do |example|
      submit_request(example.metadata)
    end

    it "returns a #{metadata[:response][:code]} response", **options do |example|
      assert_response_matches_metadata(example.metadata, &block)
      example.instance_exec(response, &block) if block_given?
    end
  end
end

#schema(value) ⇒ Object 



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

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