Allow tests to be run without generating docs

By providing the 'document: false' metadata, tests will be run but no swagger
documentation will be generated for the tagged example groups. It works on all
kinds of example groups (responses, verbs, paths etc..).

README.md

@@ -454,12 +454,30 @@ end
 
 ### Running tests without documenting ###
 
-If you want to use Rswag for testing without adding it to you swagger docs, you can simply nullify the response metadata after the test run.
-
+If you want to use Rswag for testing without adding it to you swagger docs, you can provide the document tag:
 ```ruby
-after do |example|
-  example.metadata[:response] = null
-end
+describe 'Blogs API' do
+  path '/blogs/{blog_id}' do
+    get 'Retrieves a blog' do
+      # documentation is now disabled for this response only
+      response 200, 'blog found', document: false do
+        ...
+```
+
+You can also reenable documentation for specific responses only:
+```ruby
+# documentation is now disabled
+describe 'Blogs API', document: false do
+  path '/blogs/{blog_id}' do
+    get 'Retrieves a blog' do
+      # documentation is reenabled for this response only
+      response 200, 'blog found', document: true do
+        ...
+      end
+
+      response 401, 'special case' do
+        ...
+      end
 ```
 
 ### Route Prefix for Swagger JSON Endpoints ###

rswag-specs/lib/rswag/specs/swagger_formatter.rb

@@ -25,7 +25,11 @@ module Rswag
           metadata = notification.metadata
         end
 
+        # !metadata[:document] won't work, since nil means we should generate
+        # docs.
+        return if metadata[:document] == false
         return unless metadata.has_key?(:response)
+
         swagger_doc = @config.get_swagger_doc(metadata[:swagger_doc])
         swagger_doc.deep_merge!(metadata_to_swagger(metadata))
       end

rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb

@@ -26,23 +26,37 @@ module Rswag
           {
             path_item: { template: '/blogs' },
             operation: { verb: :post, summary: 'Creates a blog' },
-            response: { code: '201', description: 'blog created' }
+            response: { code: '201', description: 'blog created' },
+            document: document
           }
         end
 
-        it 'converts to swagger and merges into the corresponding swagger doc' do
-          expect(swagger_doc).to match(
-            paths: {
-              '/blogs' => {
-                post: {
-                  summary: 'Creates a blog',
-                  responses: {
-                    '201' => { description: 'blog created' }
+        context 'with the document tag set to false' do
+          let(:document) { false }
+
+          it 'does not update the swagger doc' do
+            expect(swagger_doc).to be_empty
+          end
+        end
+
+        context 'with the document tag set to anything but false' do
+          # anything works, including its absence when specifying responses.
+          let(:document) { nil }
+
+          it 'converts to swagger and merges into the corresponding swagger doc' do
+            expect(swagger_doc).to match(
+              paths: {
+                '/blogs' => {
+                  post: {
+                    summary: 'Creates a blog',
+                    responses: {
+                      '201' => { description: 'blog created' }
+                    }
                   }
                 }
               }
-            }
-          )
+            )
+          end
         end
       end