Merge pull request #255 from fooki/skip-documentation

Allow tests to be run without generating docs

README.md

@@ -454,11 +454,29 @@ 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
+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
 ```
 

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,10 +26,23 @@ 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
 
+        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: {
@@ -45,6 +58,7 @@ module Rswag
             )
           end
         end
+      end
 
       describe '#stop' do
         before do