issue #582: document file response

- make it ruby 2.3.3 compatible
- updates README
- adds changelog entry

Author: LeFnord

Diff for: .rubocop_todo.yml

@@ -18,7 +18,7 @@ Metrics/BlockLength:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 265
+  Max: 275
 
 # Offense count: 12
 Metrics/CyclomaticComplexity:

Diff for: CHANGELOG.md

@@ -2,6 +2,8 @@
 
 #### Features
 
+* [#583](https://github.com/ruby-grape/grape-swagger/pull/583): Issue #582: document file response - [@LeFnord](https://github.com/LeFnord).
+
 * Your contribution here.
 
 #### Fixes

Diff for: README.md

@@ -397,6 +397,7 @@ add_swagger_documentation \
 * [Setting a Swagger default value](#default-value)
 * [Response documentation](#response)
 * [Changing default status codes](#change-status)
+* [File response](#file-response)
 * [Extensions](#extensions)
 
 
@@ -826,6 +827,32 @@ end
 },
 ```
 
+<a name="file-response" />
+#### File response
+
+Set `success` to `File` and sets also produces. If produces wasn't set, it defaults to `application/octet-stream`.
+```ruby
+desc 'Get a file',
+    success: File
+get do
+  # your file reponse
+end
+…
+```
+
+```json
+"produces": [
+  "application/octet-stream"
+],
+"responses": {
+  "200": {
+    "description": "Get a file",
+    "schema": {
+      "type": "file"
+    }
+  }
+}
+```
 
 <a name="extensions" />
 #### Extensions
@@ -1079,13 +1106,13 @@ role - only admins can see this endpoint.
 <a name="md_usage" />
 ## Markdown in Detail (deprecated)
 
-Usage of option `markdown` won't no longer be supported,
+Usage of option `markdown` will no longer be supported,
 cause OAPI accepts [GFM](https://help.github.com/articles/github-flavored-markdown) and plain text.
 (see: [description of `Info`](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#info-object))
 
 
 <a="example" />
-## Example
+## Examples
 
 Go into example directory and run it: `$ bundle exec rackup`
 go to: `http://localhost:9292/swagger_doc` to get it
@@ -1106,9 +1133,7 @@ class NamespaceApi < Grape::API
     desc 'Document root'
     get '/' do
     end
-  end
 
-  namespace :hudson do
     desc 'This gets something.',
       notes: '_test_'
 
@@ -1117,12 +1142,12 @@ class NamespaceApi < Grape::API
     end
   end
 
-  namespace :colorado do
-    desc 'This gets something for URL using - separator.',
-      notes: '_test_'
-
-    get '/simple-test' do
-      { bla: 'something' }
+  namespace :download do
+    desc 'download files',
+         success: File,
+         produces: ['text/csv']
+    get ':id' do
+      # file response
     end
   end
 end

Diff for: lib/grape-swagger/doc_methods/status_codes.rb

@@ -8,9 +8,7 @@ def get
             post: { code: 201, message: 'created {item}' },
             put: { code: 200, message: 'updated {item}' },
             patch: { code: 200, message: 'patched {item}' },
-            # 200 for delete would only be used, if a success entity is given,
-            # else it would be set to 204
-            delete: { code: 200, message: 'deleted {item}' },
+            delete: { code: 204, message: 'deleted {item}' },
             head: { code: 200, message: 'head {item}' },
             options: { code: 200, message: 'option {item}' }
           }

Diff for: lib/grape-swagger/endpoint.rb

@@ -138,6 +138,9 @@ def description_object(route)
     end
 
     def produces_object(route, format)
+      return ['application/octet-stream'] if file_response?(route.attributes.success) &&
+                                             !route.attributes.produces.present?
+
       mime_types = GrapeSwagger::DocMethods::ProducesConsumes.call(format)
 
       route_mime_types = [:formats, :content_types, :produces].map do |producer|
@@ -185,13 +188,14 @@ def response_object(route)
 
       codes.each_with_object({}) do |value, memo|
         memo[value[:code]] = { description: value[:message] }
+        next build_file_response(memo[value[:code]]) if file_response?(value[:model])
 
         response_model = @item
         response_model = expose_params_from_model(value[:model]) if value[:model]
 
-        if memo.key?(200) && route.request_method == 'DELETE' && value[:model].nil?
-          memo[204] = memo.delete(200)
-          value[:code] = 204
+        if route.request_method == 'DELETE' && !value[:model].nil?
+          memo[200] = memo.delete(204)
+          value[:code] = 200
         end
 
         next if memo.key?(204)
@@ -201,7 +205,7 @@ def response_object(route)
         # TODO: proof that the definition exist, if model isn't specified
         reference = { '$ref' => "#/definitions/#{response_model}" }
         memo[value[:code]][:schema] = if route.options[:is_array] && value[:code] < 300
-                                        { 'type' => 'array', 'items' => reference }
+                                        { type: 'array', items: reference }
                                       else
                                         reference
                                       end
@@ -235,6 +239,14 @@ def tag_object(route)
 
     private
 
+    def file_response?(value)
+      value.to_s.casecmp('file').zero? ? true : false
+    end
+
+    def build_file_response(memo)
+      memo['schema'] = { type: 'file' }
+    end
+
     def partition_params(route)
       declared_params = route.settings[:declared_params] if route.settings[:declared_params].present?
       required = merge_params(route)

Diff for: spec/issues/582_file_response_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe '#582 respond with a file' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_582 do
+        desc 'produces given',
+             success: File,
+             produces: ['application/pdf', 'text/csv']
+        get '/produces_given' do
+          'responds a file'
+        end
+
+        desc 'automatic produces',
+             success: 'file'
+        get '/automatic_produces' do
+          'responds a file'
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  describe 'produces given' do
+    let(:produces) { subject['paths']['/issue_582/produces_given']['get']['produces'] }
+    let(:response) { subject['paths']['/issue_582/produces_given']['get']['responses']['200'] }
+
+    specify do
+      expect(produces).to eql ['application/pdf', 'text/csv']
+      expect(response).to include 'schema'
+      expect(response['schema']).to eql 'type' => 'file'
+    end
+  end
+
+  describe 'automatic_produces' do
+    let(:produces) { subject['paths']['/issue_582/automatic_produces']['get']['produces'] }
+    let(:response) { subject['paths']['/issue_582/automatic_produces']['get']['responses']['200'] }
+
+    specify do
+      expect(produces).to eql ['application/octet-stream']
+      expect(response).to include 'schema'
+      expect(response['schema']).to eql 'type' => 'file'
+    end
+  end
+end