Rename response_examples to examples for consistent DSL

Special handling `examples` invocation with no parameters to avoid
overriding the `examples` method of rspec-core ExampleGroup

README.md

@@ -264,7 +264,7 @@ end
 
 ### Response examples ###
 
-You can provide custom response examples to the generated swagger file by calling the method `response_examples` inside the response block:
+You can provide custom response examples to the generated swagger file by calling the method `examples` inside the response block:
 
 ```ruby
 # spec/integration/blogs_spec.rb
@@ -275,7 +275,7 @@ describe 'Blogs API' do
     get 'Retrieves a blog' do
 
       response 200, 'blog found' do
-        response_examples 'application/json' => {
+        examples 'application/json' => {
             id: 1,
             title: 'Hello world!',
             content: '...'

rswag-specs/lib/rswag/specs/example_group_helpers.rb

@@ -61,7 +61,11 @@ module Rswag
         metadata[:response][:headers][name] = attributes
       end
 
-      def response_examples(example)
+      # 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
+      def examples(example = nil)
+        return super() if example.nil?
         metadata[:response][:examples] = example
       end
 

rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb

@@ -151,6 +151,25 @@ module Rswag
           )
         end
       end
+
+      describe '#examples(example)' do
+        let(:json_example) do
+          {
+            'application/json' => {
+              foo: 'bar'
+            }
+          }
+        end
+        let(:api_metadata) { { response: {} } }
+
+        before do
+          subject.examples(json_example)
+        end
+
+        it "adds to the 'response examples' metadata" do
+          expect(api_metadata[:response][:examples]).to eq(json_example)
+        end
+      end
     end
   end
 end

test-app/spec/integration/blogs_spec.rb

@@ -56,7 +56,7 @@ describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
 
         schema '$ref' => '#/definitions/blog'
 
-        response_examples 'application/json' => {
+        examples 'application/json' => {
             id: 1,
             title: 'Hello world!',
             content: 'Hello world and hello universe. Thank you all very much!!!'