Added support for set the 'collectionFormat' of arrays (#504)

Author: rczjns

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 #### Features
 
+* [#504](https://github.com/ruby-grape/grape-swagger/pull/504): Added support for set the 'collectionFormat' of arrays - [@rczjns](https://github.com/rczjns).
 * [#502](https://github.com/ruby-grape/grape-swagger/pull/502): Adds specs for rake tasks - [@LeFnord](https://github.com/LeFnord).
 * [#501](https://github.com/ruby-grape/grape-swagger/pull/501): Adds getting of a specified resource for Rake Tasks - [@LeFnord](https://github.com/LeFnord).
 * [#500](https://github.com/ruby-grape/grape-swagger/pull/500): Adds Rake tasks to get and validate OAPI/Swagger documentation - [@LeFnord](https://github.com/LeFnord).

README.md

@@ -550,6 +550,39 @@ end
 }
 ```
 
+#### Collection format of arrays
+
+You can set the collection format of an array, using the documentation hash.
+
+Collection format determines the format of the array if type array is used. Possible values are:
+*  csv - comma separated values foo,bar.
+*  ssv - space separated values foo bar.
+*  tsv - tab separated values foo\tbar.
+*  pipes - pipe separated values foo|bar.
+*  multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData".
+
+```ruby
+params do
+  requires :statuses, type: Array[String], documentation: { collectionFormat: 'multi' }
+end
+post :act do
+  ...
+end
+```
+
+```json
+{
+  "in": "formData",
+  "name": "statuses",
+  "type": "array",
+  "items": {
+      "type": "string"
+  },
+  "collectionFormat": "multi",
+  "required": true
+}
+```
+
 #### Multi types
 
 By default when you set multi types, the first type is selected as swagger type

lib/grape-swagger/doc_methods/parse_params.rb

@@ -66,6 +66,7 @@ def document_array_param(value_type)
               param_type = value_type[:documentation][:param_type]
               doc_type = value_type[:documentation][:type]
               type = GrapeSwagger::DocMethods::DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
+              collection_format = value_type[:documentation][:collectionFormat]
             end
 
             array_items = {
@@ -76,6 +77,7 @@ def document_array_param(value_type)
             @parsed_param[:in] = param_type || 'formData'
             @parsed_param[:items] = array_items
             @parsed_param[:type] = 'array'
+            @parsed_param[:collectionFormat] = collection_format if %w(csv ssv tsv pipes multi).include?(collection_format)
           end
         end
 

spec/swagger_v2/params_array_collection_fromat_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+describe 'Group Array Params, using collection format' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        optional :array_of_strings, type: Array[String], desc: 'array in csv collection format'
+      end
+
+      get '/array_of_strings_without_collection_format' do
+        { 'declared_params' => declared(params) }
+      end
+
+      params do
+        optional :array_of_strings, type: Array[String], desc: 'array in multi collection format', documentation: { collectionFormat: 'multi' }
+      end
+
+      get '/array_of_strings_multi_collection_format' do
+        { 'declared_params' => declared(params) }
+      end
+
+      params do
+        optional :array_of_strings, type: Array[String], documentation: { collectionFormat: 'foo' }
+      end
+
+      get '/array_of_strings_invalid_collection_format' do
+        { 'declared_params' => declared(params) }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  describe 'documentation for array parameter in default csv collectionFormat' do
+    subject do
+      get '/swagger_doc/array_of_strings_without_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_without_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false, 'description' => 'array in csv collection format' }
+        ]
+      )
+    end
+  end
+
+  describe 'documentation for array parameters in multi collectionFormat set from documentation' do
+    subject do
+      get '/swagger_doc/array_of_strings_multi_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_multi_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false, 'collectionFormat' => 'multi', 'description' => 'array in multi collection format' }
+        ]
+      )
+    end
+  end
+
+  describe 'documentation for array parameters with collectionFormat set to invalid option' do
+    subject do
+      get '/swagger_doc/array_of_strings_invalid_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_invalid_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false }
+        ]
+      )
+    end
+  end
+end