gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/api_swagger_v2_param_type_body_nested_spec.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'moving body/formData Params to definitions' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class NestedBodyParamTypeApi < Grape::API
+        namespace :simple_nested_params do
+          desc 'post in body with nested parameters',
+               detail: 'more details description',
+               success: Entities::UseNestedWithAddress
+          params do
+            optional :contact, type: Hash, documentation: { additional_properties: true } do
+              requires :name, type: String, documentation: { desc: 'name', in: 'body' }
+              optional :addresses, type: Array do
+                requires :street, type: String, documentation: { desc: 'street', in: 'body' }
+                requires :postcode, type: String, documentation: { desc: 'postcode', in: 'body' }
+                requires :city, type: String, documentation: { desc: 'city', in: 'body' }
+                optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+              end
+            end
+          end
+
+          post '/in_body' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'put in body with nested parameters',
+               detail: 'more details description',
+               success: Entities::UseNestedWithAddress
+          params do
+            requires :id, type: Integer
+            optional :name, type: String, documentation: { desc: 'name', in: 'body' }
+            optional :address, type: Hash do
+              optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+              optional :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+              optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+          end
+
+          put '/in_body/:id' do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        namespace :multiple_nested_params do
+          desc 'put in body with multiple nested parameters',
+               success: Entities::UseNestedWithAddress
+          params do
+            optional :contact, type: Hash do
+              requires :name, type: String, documentation: { desc: 'name', in: 'body' }
+              optional :addresses, type: Array do
+                optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+                requires :postcode, type: Integer, documentation: { desc: 'postcode', in: 'formData' }
+                optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+                optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+              end
+              optional :delivery_address, type: Hash do
+                optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+                optional :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+                optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+                optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+              end
+            end
+          end
+
+          post '/in_body' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'put in body with multiple nested parameters',
+               success: Entities::UseNestedWithAddress
+          params do
+            requires :id, type: Integer
+            optional :name, type: String, documentation: { desc: 'name', in: 'body' }
+            optional :address, type: Hash do
+              optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+              requires :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+              optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+            optional :delivery_address, type: Hash do
+              optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+              optional :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+              optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+          end
+
+          put '/in_body/:id' do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        namespace :nested_params_array do
+          desc 'post in body with array of nested parameters',
+               detail: 'more details description',
+               success: Entities::UseNestedWithAddress
+          params do
+            optional :contacts, type: Array, documentation: { additional_properties: false } do
+              requires :name, type: String, documentation: { desc: 'name', in: 'body' }
+              optional :addresses, type: Array do
+                requires :street, type: String, documentation: { desc: 'street', in: 'body' }
+                requires :postcode, type: String, documentation: { desc: 'postcode', in: 'body' }
+                requires :city, type: String, documentation: { desc: 'city', in: 'body' }
+                optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+              end
+            end
+          end
+
+          post '/in_body' do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::NestedBodyParamTypeApi
+  end
+
+  describe 'nested body parameters given' do
+    subject do
+      get '/swagger_doc/simple_nested_params'
+      JSON.parse(last_response.body)
+    end
+
+    describe 'POST' do
+      specify do
+        expect(subject['paths']['/simple_nested_params/in_body']['post']['parameters']).to eql(
+          [
+            { 'name' => 'postSimpleNestedParamsInBody', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/postSimpleNestedParamsInBody' } }
+          ]
+        )
+      end
+
+      specify do
+        expect(subject['definitions']['postSimpleNestedParamsInBody']).to eql(
+          'type' => 'object',
+          'properties' => {
+            'contact' => {
+              'type' => 'object',
+              'additionalProperties' => true,
+              'properties' => {
+                'name' => { 'type' => 'string', 'description' => 'name' },
+                'addresses' => {
+                  'type' => 'array',
+                  'items' => {
+                    'type' => 'object',
+                    'properties' => {
+                      'street' => { 'type' => 'string', 'description' => 'street' },
+                      'postcode' => { 'type' => 'string', 'description' => 'postcode' },
+                      'city' => { 'type' => 'string', 'description' => 'city' },
+                      'country' => { 'type' => 'string', 'description' => 'country' }
+                    },
+                    'required' => %w[street postcode city]
+                  }
+                }
+              },
+              'required' => %w[name]
+            }
+          },
+          'description' => 'post in body with nested parameters'
+        )
+      end
+    end
+
+    describe 'PUT' do
+      specify do
+        expect(subject['paths']['/simple_nested_params/in_body/{id}']['put']['parameters']).to eql(
+          [
+            { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true },
+            { 'name' => 'putSimpleNestedParamsInBodyId', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/putSimpleNestedParamsInBodyId' } }
+          ]
+        )
+      end
+
+      specify do
+        expect(subject['definitions']['putSimpleNestedParamsInBodyId']).to eql(
+          'type' => 'object',
+          'properties' => {
+            'name' => { 'type' => 'string', 'description' => 'name' },
+            'address' => {
+              'type' => 'object',
+              'properties' => {
+                'street' => { 'type' => 'string', 'description' => 'street' },
+                'postcode' => { 'type' => 'string', 'description' => 'postcode' },
+                'city' => { 'type' => 'string', 'description' => 'city' },
+                'country' => { 'type' => 'string', 'description' => 'country' }
+              }
+            }
+          },
+          'description' => 'put in body with nested parameters'
+        )
+      end
+    end
+  end
+
+  describe 'multiple nested body parameters given' do
+    subject do
+      get '/swagger_doc/multiple_nested_params'
+      JSON.parse(last_response.body)
+    end
+
+    describe 'POST' do
+      specify do
+        expect(subject['paths']['/multiple_nested_params/in_body']['post']['parameters']).to eql(
+          [
+            {
+              'name' => 'postMultipleNestedParamsInBody',
+              'in' => 'body',
+              'required' => true,
+              'schema' => { '$ref' => '#/definitions/postMultipleNestedParamsInBody' }
+            }
+          ]
+        )
+      end
+
+      specify do
+        expect(subject['definitions']['postMultipleNestedParamsInBody']).to eql(
+          'type' => 'object',
+          'properties' => {
+            'contact' => {
+              'type' => 'object',
+              'properties' => {
+                'name' => { 'type' => 'string', 'description' => 'name' },
+                'addresses' => {
+                  'type' => 'array',
+                  'items' => {
+                    'type' => 'object',
+                    'properties' => {
+                      'street' => { 'type' => 'string', 'description' => 'street' },
+                      'postcode' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'postcode' },
+                      'city' => { 'type' => 'string', 'description' => 'city' },
+                      'country' => { 'type' => 'string', 'description' => 'country' }
+                    },
+                    'required' => ['postcode']
+                  }
+                },
+                'delivery_address' => {
+                  'type' => 'object',
+                  'properties' => {
+                    'street' => { 'type' => 'string', 'description' => 'street' },
+                    'postcode' => { 'type' => 'string', 'description' => 'postcode' },
+                    'city' => { 'type' => 'string', 'description' => 'city' },
+                    'country' => { 'type' => 'string', 'description' => 'country' }
+                  }
+                }
+              },
+              'required' => %w[name]
+            }
+          },
+          'description' => 'put in body with multiple nested parameters'
+        )
+      end
+    end
+
+    describe 'PUT' do
+      specify do
+        expect(subject['paths']['/multiple_nested_params/in_body/{id}']['put']['parameters']).to eql(
+          [
+            { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true },
+            { 'name' => 'putMultipleNestedParamsInBodyId', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/putMultipleNestedParamsInBodyId' } }
+          ]
+        )
+      end
+
+      specify do
+        expect(subject['definitions']['putMultipleNestedParamsInBodyId']).to eql(
+          'type' => 'object',
+          'properties' => {
+            'name' => { 'type' => 'string', 'description' => 'name' },
+            'address' => {
+              'type' => 'object',
+              'properties' => {
+                'street' => { 'type' => 'string', 'description' => 'street' },
+                'postcode' => { 'type' => 'string', 'description' => 'postcode' },
+                'city' => { 'type' => 'string', 'description' => 'city' },
+                'country' => { 'type' => 'string', 'description' => 'country' }
+              },
+              'required' => ['postcode']
+            },
+            'delivery_address' => {
+              'type' => 'object',
+              'properties' => {
+                'street' => { 'type' => 'string', 'description' => 'street' },
+                'postcode' => { 'type' => 'string', 'description' => 'postcode' },
+                'city' => { 'type' => 'string', 'description' => 'city' },
+                'country' => { 'type' => 'string', 'description' => 'country' }
+              }
+            }
+          },
+          'description' => 'put in body with multiple nested parameters'
+        )
+      end
+    end
+  end
+
+  describe 'array of nested body parameters given' do
+    subject do
+      get '/swagger_doc/nested_params_array'
+      JSON.parse(last_response.body)
+    end
+
+    describe 'POST' do
+      specify do
+        expect(subject['paths']['/nested_params_array/in_body']['post']['parameters']).to eql(
+          [
+            { 'name' => 'postNestedParamsArrayInBody', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/postNestedParamsArrayInBody' } }
+          ]
+        )
+      end
+
+      specify do
+        expect(subject['definitions']['postNestedParamsArrayInBody']).to eql(
+          'type' => 'object',
+          'properties' => {
+            'contacts' => {
+              'type' => 'array',
+              'items' => {
+                'type' => 'object',
+                'additionalProperties' => false,
+                'properties' => {
+                  'name' => { 'type' => 'string', 'description' => 'name' },
+                  'addresses' => {
+                    'type' => 'array',
+                    'items' => {
+                      'type' => 'object',
+                      'properties' => {
+                        'street' => { 'type' => 'string', 'description' => 'street' },
+                        'postcode' => { 'type' => 'string', 'description' => 'postcode' },
+                        'city' => { 'type' => 'string', 'description' => 'city' },
+                        'country' => { 'type' => 'string', 'description' => 'country' }
+                      },
+                      'required' => %w[street postcode city]
+                    }
+                  }
+                },
+                'required' => %w[name]
+              }
+            }
+          },
+          'description' => 'post in body with array of nested parameters'
+        )
+      end
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `header`' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class BodyParamTypeApi < Grape::API
+        namespace :wo_entities do
+          desc 'post in body /wo entity'
+          params do
+            requires :in_body_1, type: Integer, documentation: { desc: 'in_body_1', param_type: 'body' }
+            optional :in_body_2, type: String, documentation: { desc: 'in_body_2', param_type: 'body' }
+            optional :in_body_3, type: String, documentation: { desc: 'in_body_3', param_type: 'body' }
+          end
+
+          post '/in_body' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'put in body /wo entity'
+          params do
+            requires :key, type: Integer
+            optional :in_body_1, type: Integer, documentation: { desc: 'in_body_1', param_type: 'body' }
+            optional :in_body_2, type: String, documentation: { desc: 'in_body_2', param_type: 'body' }
+            optional :in_body_3, type: String, documentation: { desc: 'in_body_3', param_type: 'body' }
+          end
+
+          put '/in_body/:key' do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        namespace :with_entities do
+          desc 'post in body with entity',
+               success: ::Entities::ResponseItem
+          params do
+            requires :name, type: String, documentation: { desc: 'name', param_type: 'body' }
+          end
+
+          post '/in_body' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'put in body with entity',
+               success: ::Entities::ResponseItem
+          params do
+            requires :id, type: Integer
+            optional :name, type: String, documentation: { desc: 'name', param_type: 'body' }
+          end
+
+          put '/in_body/:id' do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        namespace :with_entity_param do
+          desc 'put in body with entity parameter'
+          params do
+            optional :data, type: ::Entities::NestedModule::ApiResponse, documentation: { desc: 'request data' }
+          end
+
+          post do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::BodyParamTypeApi
+  end
+
+  describe 'no entity given' do
+    subject do
+      get '/swagger_doc/wo_entities'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/wo_entities/in_body']['post']['parameters']).to eql(
+        [
+          { 'name' => 'postWoEntitiesInBody', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/postWoEntitiesInBody' } }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['definitions']['postWoEntitiesInBody']).to eql(
+        'description' => 'post in body /wo entity',
+        'type' => 'object',
+        'properties' => {
+          'in_body_1' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'in_body_1' },
+          'in_body_2' => { 'type' => 'string', 'description' => 'in_body_2' },
+          'in_body_3' => { 'type' => 'string', 'description' => 'in_body_3' }
+        },
+        'required' => ['in_body_1']
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/wo_entities/in_body/{key}']['put']['parameters']).to eql(
+        [
+          { 'in' => 'path', 'name' => 'key', 'type' => 'integer', 'format' => 'int32', 'required' => true },
+          { 'name' => 'putWoEntitiesInBodyKey', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/putWoEntitiesInBodyKey' } }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['definitions']['putWoEntitiesInBodyKey']).to eql(
+        'description' => 'put in body /wo entity',
+        'type' => 'object',
+        'properties' => {
+          'in_body_1' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'in_body_1' },
+          'in_body_2' => { 'type' => 'string', 'description' => 'in_body_2' },
+          'in_body_3' => { 'type' => 'string', 'description' => 'in_body_3' }
+        }
+      )
+    end
+  end
+
+  describe 'entity given' do
+    subject do
+      get '/swagger_doc/with_entities'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/with_entities/in_body']['post']['parameters']).to eql(
+        [
+          { 'name' => 'postWithEntitiesInBody', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/postWithEntitiesInBody' } }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['definitions']['postWithEntitiesInBody']).to eql(
+        'type' => 'object',
+        'properties' => {
+          'name' => { 'type' => 'string', 'description' => 'name' }
+        },
+        'required' => ['name'],
+        'description' => 'post in body with entity'
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/with_entities/in_body/{id}']['put']['parameters']).to eql(
+        [
+          { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true },
+          { 'name' => 'putWithEntitiesInBodyId', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/putWithEntitiesInBodyId' } }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['definitions']['putWithEntitiesInBodyId']).to eql(
+        'type' => 'object',
+        'properties' => {
+          'name' => { 'type' => 'string', 'description' => 'name' }
+        },
+        'description' => 'put in body with entity'
+      )
+    end
+  end
+
+  describe 'complex entity given' do
+    let(:request_parameters_definition) do
+      [
+        {
+          'name' => 'postWithEntityParam',
+          'in' => 'body',
+          'required' => true,
+          'schema' => {
+            '$ref' => '#/definitions/postWithEntityParam'
+          }
+        }
+      ]
+    end
+
+    let(:request_body_parameters_definition) do
+      {
+        'type' => 'object',
+        'properties' => {
+          'data' => {
+            '$ref' => '#/definitions/NestedModule_ApiResponse',
+            'description' => 'request data'
+          }
+        },
+        'description' => 'put in body with entity parameter'
+      }
+    end
+
+    subject do
+      get '/swagger_doc/with_entity_param'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/with_entity_param']['post']['parameters']).to eql(request_parameters_definition)
+    end
+
+    specify do
+      expect(subject['definitions']['NestedModule_ApiResponse']).not_to be_nil
+    end
+
+    specify do
+      expect(subject['definitions']['postWithEntityParam']).to eql(request_body_parameters_definition)
+    end
+  end
+end