gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/param_values_spec.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+# require 'grape_version'
+
+describe 'Convert values to enum or Range' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'plain_array' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :letter, type: String, values: %w[a b c]
+      end
+      post :plain_array do
+        { message: 'hi' }
+      end
+
+      desc 'array_in_proc' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :letter, type: String, values: proc { %w[d e f] }
+      end
+      post :array_in_proc do
+        { message: 'hi' }
+      end
+
+      desc 'range_letter' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :letter, type: String, values: 'a'..'z'
+      end
+      post :range_letter do
+        { message: 'hi' }
+      end
+
+      desc 'range_integer' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :integer, type: Integer, values: -5..5
+      end
+      post :range_integer do
+        { message: 'hi' }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  def first_parameter_info(request)
+    get "/swagger_doc/#{request}"
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    body['paths']["/#{request}"]['post']['parameters']
+  end
+
+  context 'Plain array values' do
+    subject(:plain_array) { first_parameter_info('plain_array') }
+    it 'has values as array in enum' do
+      expect(plain_array).to eq [{
+        'in' => 'formData',
+        'name' => 'letter',
+        'type' => 'string',
+        'required' => true,
+        'enum' => %w[a b c]
+      }]
+    end
+  end
+
+  context 'Array in proc values' do
+    subject(:array_in_proc) { first_parameter_info('array_in_proc') }
+
+    it 'has proc returned values as array in enum' do
+      expect(array_in_proc).to eq [{
+        'in' => 'formData',
+        'name' => 'letter',
+        'type' => 'string',
+        'required' => true,
+        'enum' => %w[d e f]
+      }]
+    end
+  end
+
+  context 'Range values' do
+    subject(:range_letter) { first_parameter_info('range_letter') }
+
+    it 'has letter range values' do
+      expect(range_letter).to eq [{
+        'in' => 'formData',
+        'name' => 'letter',
+        'type' => 'string',
+        'required' => true
+      }]
+    end
+
+    subject(:range_integer) { first_parameter_info('range_integer') }
+
+    it 'has integer range values' do
+      expect(range_integer).to eq [{
+        'in' => 'formData',
+        'name' => 'integer',
+        'type' => 'integer',
+        'required' => true,
+        'format' => 'int32',
+        'minimum' => -5,
+        'maximum' => 5
+      }]
+    end
+  end
+end
+
+describe 'Convert values to enum for float range and not arrays inside a proc', if: GrapeVersion.satisfy?('>= 0.11.0') do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'non_array_in_proc' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :letter, type: String, values: proc { 'string' }
+      end
+      post :non_array_in_proc do
+        { message: 'hi' }
+      end
+
+      desc 'range_float' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :float, type: Float, values: -5.0..5.0
+      end
+      post :range_float do
+        { message: 'hi' }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  def first_parameter_info(request)
+    get "/swagger_doc/#{request}"
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    body['paths']["/#{request}"]['post']['parameters']
+  end
+
+  context 'Non array in proc values' do
+    subject(:non_array_in_proc) { first_parameter_info('non_array_in_proc') }
+
+    it 'has proc returned value as string in enum' do
+      expect(non_array_in_proc).to eq [{
+        'in' => 'formData',
+        'name' => 'letter',
+        'type' => 'string',
+        'required' => true,
+        'enum' => %w[string]
+      }]
+    end
+  end
+
+  context 'Range values' do
+    subject(:range_float) { first_parameter_info('range_float') }
+
+    it 'has float range values as string' do
+      expect(range_float).to eq [{
+        'in' => 'formData',
+        'name' => 'float',
+        'type' => 'number',
+        'required' => true,
+        'format' => 'float'
+      }]
+    end
+  end
+end

data/spec/swagger_v2/params_array_collection_format_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+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
+
+      params do
+        optional :array_of_strings, type: Array[String], desc: 'array in brackets collection format', documentation: { collectionFormat: 'brackets' }
+      end
+
+      get '/array_of_strings_brackets_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' => 'query', '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' => 'query', '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 in brackets collectionFormat set from documentation' do
+    subject do
+      get '/swagger_doc/array_of_strings_brackets_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_brackets_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'query', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false, 'collectionFormat' => 'brackets', 'description' => 'array in brackets 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' => 'query', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false }
+        ]
+      )
+    end
+  end
+end

data/spec/swagger_v2/params_array_spec.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Group Params as Array' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  [true, false].each do |array_use_braces|
+    context "when array_use_braces option is set to #{array_use_braces}" do
+      let(:braces) { array_use_braces ? '[]' : '' }
+
+      let(:app) do
+        Class.new(Grape::API) do
+          format :json
+
+          desc 'groups' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            requires :required_group, type: Array do
+              requires :required_param_1
+              requires :required_param_2
+            end
+          end
+          post '/groups' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'type_given' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            requires :typed_group, type: Array do
+              requires :id, type: Integer, desc: 'integer given'
+              requires :name, type: String, desc: 'string given'
+              optional :email, type: String, desc: 'email given'
+              optional :others, type: Integer, values: [1, 2, 3]
+            end
+          end
+          post '/type_given' do
+            { 'declared_params' => declared(params) }
+          end
+
+          # as body parameters it would be interpreted a bit different,
+          # cause it could not be distinguished anymore, so this would be translated to one array,
+          # see also next example for the difference
+          desc 'array_of_type' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+
+          params do
+            requires :array_of_string, type: Array[String], documentation: { param_type: 'body', desc: 'nested array of strings' }
+            requires :array_of_integer, type: Array[Integer], documentation: { param_type: 'body', desc: 'nested array of integers' }
+          end
+
+          post '/array_of_type' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'object_and_array' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+
+          params do
+            requires :array_of_string, type: Array[String], documentation: { param_type: 'body', desc: 'array of strings' }
+            requires :integer_value, type: Integer, documentation: { param_type: 'body', desc: 'integer value' }
+          end
+
+          post '/object_and_array' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'array_of_type_in_form' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+
+          params do
+            requires :array_of_string, type: Array[String]
+            requires :array_of_integer, type: Array[Integer]
+          end
+
+          post '/array_of_type_in_form' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'array_of_entities' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+
+          params do
+            requires :array_of_entities, type: Array[Entities::ApiError]
+          end
+
+          post '/array_of_entities' do
+            { 'declared_params' => declared(params) }
+          end
+
+          add_swagger_documentation array_use_braces: array_use_braces
+        end
+      end
+
+      describe 'retrieves the documentation for grouped parameters' do
+        subject do
+          get '/swagger_doc/groups'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['paths']['/groups']['post']['parameters']).to eql(
+            [
+              { 'in' => 'formData', 'name' => "required_group#{braces}[required_param_1]", 'required' => true, 'type' => 'array', 'items' => { 'type' => 'string' } },
+              { 'in' => 'formData', 'name' => "required_group#{braces}[required_param_2]", 'required' => true, 'type' => 'array', 'items' => { 'type' => 'string' } }
+            ]
+          )
+        end
+      end
+
+      describe 'retrieves the documentation for typed group parameters' do
+        subject do
+          get '/swagger_doc/type_given'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['paths']['/type_given']['post']['parameters']).to eql(
+            [
+              { 'in' => 'formData', 'name' => "typed_group#{braces}[id]", 'description' => 'integer given', 'type' => 'array', 'items' => { 'type' => 'integer', 'format' => 'int32' }, 'required' => true },
+              { 'in' => 'formData', 'name' => "typed_group#{braces}[name]", 'description' => 'string given', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true },
+              { 'in' => 'formData', 'name' => "typed_group#{braces}[email]", 'description' => 'email given', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false },
+              { 'in' => 'formData', 'name' => "typed_group#{braces}[others]", 'type' => 'array', 'items' => { 'type' => 'integer', 'format' => 'int32', 'enum' => [1, 2, 3] }, 'required' => false }
+            ]
+          )
+        end
+      end
+
+      describe 'retrieves the documentation for parameters that are arrays of primitive types' do
+        subject do
+          get '/swagger_doc/array_of_type'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['definitions']['postArrayOfType']['type']).to eql 'array'
+          expect(subject['definitions']['postArrayOfType']['items']).to eql(
+            'type' => 'object',
+            'properties' => {
+              'array_of_string' => {
+                'items' => { 'type' => 'string' }, 'type' => 'array', 'description' => 'nested array of strings'
+              },
+              'array_of_integer' => {
+                'items' => { 'type' => 'integer', 'format' => 'int32' }, 'type' => 'array', 'description' => 'nested array of integers'
+              }
+            },
+            'required' => %w[array_of_string array_of_integer]
+          )
+        end
+      end
+
+      describe 'documentation for simple and array parameters' do
+        subject do
+          get '/swagger_doc/object_and_array'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['definitions']['postObjectAndArray']['type']).to eql 'object'
+          expect(subject['definitions']['postObjectAndArray']['properties']).to eql(
+            'array_of_string' => {
+              'type' => 'array',
+              'description' => 'array of strings',
+              'items' => {
+                'type' => 'string'
+              }
+            },
+            'integer_value' => {
+              'type' => 'integer', 'format' => 'int32', 'description' => 'integer value'
+            }
+          )
+        end
+      end
+
+      describe 'retrieves the documentation for typed group parameters' do
+        subject do
+          get '/swagger_doc/array_of_type_in_form'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['paths']['/array_of_type_in_form']['post']['parameters']).to eql(
+            [
+              { 'in' => 'formData', 'name' => "array_of_string#{braces}", 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true },
+              { 'in' => 'formData', 'name' => "array_of_integer#{braces}", 'type' => 'array', 'items' => { 'type' => 'integer', 'format' => 'int32' }, 'required' => true }
+            ]
+          )
+        end
+      end
+
+      describe 'documentation for entity array parameters' do
+        let(:parameters) do
+          [
+            {
+              'in' => 'formData',
+              'name' => "array_of_entities#{braces}",
+              'type' => 'array',
+              'items' => {
+                '$ref' => '#/definitions/ApiError'
+              },
+              'required' => true
+            }
+          ]
+        end
+
+        subject do
+          get '/swagger_doc/array_of_entities'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['definitions']['ApiError']).not_to be_blank
+          expect(subject['paths']['/array_of_entities']['post']['parameters']).to eql(parameters)
+        end
+      end
+    end
+  end
+end

data/spec/swagger_v2/params_example_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Param example' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        requires :id, type: Integer, documentation: { example: 123 }
+        optional :name, type: String, documentation: { example: 'Person' }
+        optional :obj, type: 'Object', documentation: { example: { 'foo' => 'bar' } }
+      end
+
+      post '/endpoint_with_examples' do
+        { 'declared_params' => declared(params) }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  describe 'documentation with parameter examples' do
+    subject do
+      get '/swagger_doc/endpoint_with_examples'
+      JSON.parse(last_response.body)
+    end
+
+    let(:parameters) { subject['definitions']['postEndpointWithExamples']['properties'] }
+
+    specify do
+      expect(parameters).to eql(
+        { 'id' => { 'type' => 'integer', 'format' => 'int32', 'example' => 123 }, 'name' => { 'type' => 'string', 'example' => 'Person' }, 'obj' => { 'type' => 'Object', 'example' => { 'foo' => 'bar' } } }
+      )
+    end
+  end
+end

data/spec/swagger_v2/params_hash_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Group Params as Hash' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'use groups' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :required_group, type: Hash do
+          requires :required_param_1
+          requires :required_param_2
+        end
+      end
+      post '/use_groups' do
+        { 'declared_params' => declared(params) }
+      end
+
+      desc 'use given type' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :typed_group, type: Hash do
+          requires :id, type: Integer, desc: 'integer given'
+          requires :name, type: String, desc: 'string given'
+          optional :email, type: String, desc: 'email given'
+          optional :others, type: Integer, values: [1, 2, 3]
+        end
+      end
+      post '/use_given_type' do
+        { 'declared_params' => declared(params) }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  describe 'grouped parameters' do
+    subject do
+      get '/swagger_doc/use_groups'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_groups']['post']).to include('parameters')
+      expect(subject['paths']['/use_groups']['post']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'required_group[required_param_1]', 'type' => 'string', 'required' => true },
+          { 'in' => 'formData', 'name' => 'required_group[required_param_2]', 'type' => 'string', 'required' => true }
+        ]
+      )
+    end
+  end
+
+  describe 'grouped parameters with given type' do
+    subject do
+      get '/swagger_doc/use_given_type'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_given_type']['post']).to include('parameters')
+      expect(subject['paths']['/use_given_type']['post']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'typed_group[id]', 'description' => 'integer given', 'type' => 'integer', 'required' => true, 'format' => 'int32' },
+          { 'in' => 'formData', 'name' => 'typed_group[name]', 'description' => 'string given', 'type' => 'string', 'required' => true },
+          { 'in' => 'formData', 'name' => 'typed_group[email]', 'description' => 'email given', 'type' => 'string', 'required' => false },
+          { 'in' => 'formData', 'name' => 'typed_group[others]', 'type' => 'integer', 'required' => false, 'format' => 'int32', 'enum' => [1, 2, 3] }
+        ]
+      )
+    end
+  end
+end