grape-swagger 1.1.0 → 1.4.2

data/spec/support/model_parsers/representable_parser.rb

@@ -218,22 +218,22 @@ RSpec.shared_context 'representable swagger example' do
 
   let(:swagger_nested_type) do
     {
-      'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' },
-      'UseItemResponseAsType' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, 'responses' => { 'description' => '', 'type' => 'ResponseItem' } }, 'description' => 'This returns something' }
+      'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' },
+      'UseItemResponseAsType' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, 'responses' => { 'description' => '', 'type' => 'ResponseItem' } }, 'description' => 'UseItemResponseAsType model' }
     }
   end
 
   let(:swagger_entity_as_response_object) do
     {
-      'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' },
+      'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' },
       'ResponseItem' => { 'type' => 'object', 'properties' => { 'id' => { 'description' => '', 'type' => 'integer', 'format' => 'int32' }, 'name' => { 'description' => '', 'type' => 'string' } } },
-      'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } }, 'description' => 'This returns something' }
+      'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } }, 'description' => 'UseResponse model' }
     }
   end
 
   let(:swagger_params_as_response_object) do
     {
-      'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' }
+      'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' }
     }
   end
 
@@ -372,7 +372,7 @@ RSpec.shared_context 'representable swagger example' do
           'type' => 'object',
           'required' => ['elements'],
           'properties' => { 'elements' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/QueryInputElement' }, 'description' => 'Set of configuration' } },
-          'description' => 'nested route inside namespace'
+          'description' => 'QueryInput model'
         },
         'QueryInputElement' => {
           'type' => 'object',
@@ -382,7 +382,7 @@ RSpec.shared_context 'representable swagger example' do
         'ApiError' => {
           'type' => 'object',
           'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } },
-          'description' => 'This gets Things.'
+          'description' => 'ApiError model'
         },
         'Something' => {
           'type' => 'object',
@@ -392,7 +392,7 @@ RSpec.shared_context 'representable swagger example' do
             'links' => { 'type' => 'array', 'items' => { 'description' => '', 'type' => 'link' } },
             'others' => { 'description' => '', 'type' => 'text' }
           },
-          'description' => 'This gets Things.'
+          'description' => 'Something model'
         }
       }
     }

data/spec/support/namespace_tags.rb

@@ -3,12 +3,15 @@
 RSpec.shared_context 'namespace example' do
   before :all do
     module TheApi
+      # rubocop:disable Lint/EmptyClass
       class CustomType; end
+      # rubocop:enable Lint/EmptyClass
 
       class NamespaceApi < Grape::API
         namespace :hudson do
           desc 'Document root'
           get '/' do
+            { message: 'hi' }
           end
         end
 

data/spec/support/the_paths_definitions.rb

@@ -8,7 +8,7 @@ RSpec.shared_context 'the api paths/defs' do
           produces: ['application/json'],
           consumes: ['application/json'],
           parameters: [
-            { in: 'body', name: 'in_body_1', description: 'in_body_1', type: 'integer', format: 'int32', required: true },
+            { in: 'body', name: 'in_body_1', description: 'in_body_1', type: 'integer', format: 'int32', required: true, example: 23 },
             { in: 'body', name: 'in_body_2', description: 'in_body_2', type: 'string', required: false },
             { in: 'body', name: 'in_body_3', description: 'in_body_3', type: 'string', required: false }
           ],
@@ -31,7 +31,7 @@ RSpec.shared_context 'the api paths/defs' do
             { in: 'path', name: 'key', description: nil, type: 'integer', format: 'int32', required: true },
             { in: 'body', name: 'in_body_1', description: 'in_body_1', type: 'integer', format: 'int32', required: true },
             { in: 'body', name: 'in_body_2', description: 'in_body_2', type: 'string', required: false },
-            { in: 'body', name: 'in_body_3', description: 'in_body_3', type: 'string', required: false }
+            { in: 'body', name: 'in_body_3', description: 'in_body_3', type: 'string', required: false, example: 'my example string' }
           ],
           responses: { 200 => { description: 'put in body /wo entity', schema: { '$ref' => '#/definitions/InBody' } } },
           tags: ['in_body'],
@@ -85,7 +85,7 @@ RSpec.shared_context 'the api paths/defs' do
     {
       type: 'object',
       properties: {
-        in_body_1: { type: 'integer', format: 'int32', description: 'in_body_1' },
+        in_body_1: { type: 'integer', format: 'int32', description: 'in_body_1', example: 23 },
         in_body_2: { type: 'string', description: 'in_body_2' },
         in_body_3: { type: 'string', description: 'in_body_3' }
       },
@@ -99,7 +99,7 @@ RSpec.shared_context 'the api paths/defs' do
       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' }
+        in_body_3: { type: 'string', description: 'in_body_3', example: 'my example string' }
       },
       required: [:in_body_1]
     }

data/spec/swagger_v2/api_swagger_v2_additional_properties_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'parsing additional_parameters' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :things do
+        class Element < Grape::Entity
+          expose :id
+        end
+
+        params do
+          optional :closed, type: Hash, documentation: { additional_properties: false, in: 'body' } do
+            requires :only
+          end
+          optional :open, type: Hash, documentation: { additional_properties: true }
+          optional :type_limited, type: Hash, documentation: { additional_properties: String }
+          optional :ref_limited, type: Hash, documentation: { additional_properties: Element }
+          optional :fallback, type: Hash, documentation: { additional_properties: { type: 'integer' } }
+        end
+        post do
+          present params
+        end
+      end
+
+      add_swagger_documentation format: :json, models: [Element]
+    end
+  end
+
+  subject do
+    get '/swagger_doc/things'
+    JSON.parse(last_response.body)
+  end
+
+  describe 'POST' do
+    specify do
+      expect(subject.dig('paths', '/things', 'post', 'parameters')).to eql(
+        [
+          { 'name' => 'Things', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/postThings' } }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject.dig('definitions', 'postThings')).to eql(
+        'type' => 'object',
+        'properties' => {
+          'closed' => {
+            'type' => 'object',
+            'additionalProperties' => false,
+            'properties' => {
+              'only' => { 'type' => 'string' }
+            },
+            'required' => ['only']
+          },
+          'open' => {
+            'type' => 'object',
+            'additionalProperties' => true
+          },
+          'type_limited' => {
+            'type' => 'object',
+            'additionalProperties' => {
+              'type' => 'string'
+            }
+          },
+          'ref_limited' => {
+            'type' => 'object',
+            'additionalProperties' => {
+              '$ref' => '#/definitions/Element'
+            }
+          },
+          'fallback' => {
+            'type' => 'object',
+            'additionalProperties' => {
+              'type' => 'integer'
+            }
+          }
+        }
+      )
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_hide_param_spec.rb

@@ -19,7 +19,7 @@ describe 'hidden flag enables a single endpoint parameter to be excluded from th
             requires :name, type: String, documentation: { desc: 'name' }
             optional :favourite_color, type: String, documentation: { desc: 'I should not be anywhere', hidden: true }
             optional :proc_param, type: String, documentation: { desc: 'I should not be anywhere', hidden: proc { true } }
-            optional :proc_with_token, type: String, documentation: { desc: 'I may be somewhere', hidden: proc { |token_owner = nil| token_owner.nil? } }
+            optional :proc_with_token, type: String, documentation: { desc: 'I may be somewhere', hidden: proc { false } }
           end
 
           post do

data/spec/swagger_v2/api_swagger_v2_mounted_spec.rb

@@ -81,6 +81,7 @@ describe 'swagger spec v2.0' do
           requires :id, type: Integer
         end
         delete '/dummy/:id' do
+          {}
         end
 
         namespace :other_thing do

data/spec/swagger_v2/api_swagger_v2_param_type_body_nested_spec.rb

@@ -13,7 +13,7 @@ describe 'moving body/formData Params to definitions' do
                detail: 'more details description',
                success: Entities::UseNestedWithAddress
           params do
-            optional :contact, type: Hash 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' }
@@ -96,6 +96,27 @@ describe 'moving body/formData Params to definitions' do
           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
@@ -126,6 +147,7 @@ describe 'moving body/formData Params to definitions' do
           'properties' => {
             'contact' => {
               'type' => 'object',
+              'additionalProperties' => true,
               'properties' => {
                 'name' => { 'type' => 'string', 'description' => 'name' },
                 'addresses' => {
@@ -280,4 +302,54 @@ describe 'moving body/formData Params to definitions' do
       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' => 'NestedParamsArrayInBody', '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

@@ -189,7 +189,7 @@ describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `h
         'type' => 'object',
         'properties' => {
           'data' => {
-            '$ref' => '#/definitions/NestedModule::ApiResponse',
+            '$ref' => '#/definitions/NestedModule_ApiResponse',
             'description' => 'request data'
           }
         },
@@ -207,7 +207,7 @@ describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `h
     end
 
     specify do
-      expect(subject['definitions']['NestedModule::ApiResponse']).not_to be_nil
+      expect(subject['definitions']['NestedModule_ApiResponse']).not_to be_nil
     end
 
     specify do

data/spec/swagger_v2/api_swagger_v2_response_with_headers_spec.rb

@@ -19,7 +19,8 @@ describe 'response with headers' do
         end
 
         desc 'A 204 can have headers too' do
-          success Hash[status: 204, message: 'No content', headers: { 'Location' => { description: 'Location of resource', type: 'string' } }]
+          foo = { status: 204, message: 'No content', headers: { 'Location' => { description: 'Location of resource', type: 'string' } } }
+          success foo
           failure [[400, 'Bad Request', Entities::ApiError, { 'application/json' => { code: 400, message: 'Bad request' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
         end
         delete '/no_content_response_headers' do
@@ -27,7 +28,8 @@ describe 'response with headers' do
         end
 
         desc 'A file can have headers too' do
-          success Hash[status: 200, model: 'File', headers: { 'Cache-Control' => { description: 'Directive for caching', type: 'string' } }]
+          foo = { status: 200, model: 'File', headers: { 'Cache-Control': { description: 'Directive for caching', type: 'string' } } }
+          success foo
           failure [[404, 'NotFound', Entities::ApiError, { 'application/json' => { code: 404, message: 'Not found' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
         end
         get '/file_response_headers' do

data/spec/swagger_v2/api_swagger_v2_response_with_models_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApiModels < Grape::API
+        format :json
+
+        desc 'This returns something',
+             success: [{ code: 200 }],
+             failure: [
+               { code: 400, message: 'NotFound', model: '' },
+               { code: 404, message: 'BadRequest', model: Entities::ApiError }
+             ]
+        get '/use-response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation(models: [Entities::UseResponse])
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiModels
+  end
+
+  describe 'uses entity as response object implicitly with route name' do
+    subject do
+      get '/swagger_doc/use-response'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use-response']['get']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns something', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '400' => { 'description' => 'NotFound' },
+          '404' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['use-response'],
+        'operationId' => 'getUseResponse'
+      )
+      expect(subject['definitions']).to eql(swagger_entity_as_response_object)
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_spec.rb

@@ -80,6 +80,7 @@ describe 'swagger spec v2.0' do
         requires :id, type: Integer
       end
       delete '/dummy/:id' do
+        {}
       end
 
       namespace :other_thing do

data/spec/swagger_v2/boolean_params_spec.rb

@@ -9,8 +9,10 @@ describe 'Boolean Params' do
 
       params do
         requires :a_boolean, type: Grape::API::Boolean
+        optional :another_boolean, type: Grape::API::Boolean, default: false
       end
       post :splines do
+        { message: 'hi' }
       end
 
       add_swagger_documentation
@@ -26,7 +28,8 @@ describe 'Boolean Params' do
 
   it 'converts boolean types' do
     expect(subject).to eq [
-      { 'in' => 'formData', 'name' => 'a_boolean', 'type' => 'boolean', 'required' => true }
+      { 'in' => 'formData', 'name' => 'a_boolean', 'type' => 'boolean', 'required' => true },
+      { 'in' => 'formData', 'name' => 'another_boolean', 'type' => 'boolean', 'required' => false, 'default' => false }
     ]
   end
 end

data/spec/swagger_v2/float_api_spec.rb

@@ -11,6 +11,7 @@ describe 'Float Params' do
         requires :a_float, type: Float
       end
       post :splines do
+        { message: 'hi' }
       end
 
       add_swagger_documentation

data/spec/swagger_v2/inheritance_and_discriminator_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Inheritance and Discriminator' do
+  before :all do
+    module InheritanceTest
+      module Entities
+        # example from https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#models-with-polymorphism-supports
+        class Pet < Grape::Entity
+          expose :type, documentation: {
+            type: 'string',
+            is_discriminator: true,
+            required: true
+          }
+          expose :name, documentation: {
+            type: 'string',
+            required: true
+          }
+        end
+
+        class Cat < Pet
+          expose :huntingSkill, documentation: {
+            type: 'string',
+            description: 'The measured skill for hunting',
+            default: 'lazy',
+            values: %w[
+              clueless
+              lazy
+              adventurous
+              aggressive
+            ]
+          }
+        end
+      end
+
+      class NameApi < Grape::API
+        add_swagger_documentation models: [Entities::Pet, Entities::Cat]
+      end
+    end
+  end
+
+  context 'Parent model' do
+    let(:app) { InheritanceTest::NameApi }
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['definitions']
+    end
+
+    specify do
+      subject['InheritanceTest_Entities_Pet'].key?('discriminator')
+      subject['InheritanceTest_Entities_Pet']['discriminator'] = 'type'
+      subject['InheritanceTest_Entities_Cat'].key?('allOf')
+    end
+  end
+end

data/spec/swagger_v2/namespace_tags_prefix_spec.rb

@@ -17,6 +17,7 @@ describe 'namespace tags check while using prefix and version' do
         namespace :hudson do
           desc 'Document root'
           get '/' do
+            { message: 'hi' }
           end
         end
 

data/spec/swagger_v2/param_multi_type_spec.rb

@@ -16,6 +16,7 @@ describe 'Params Multi Types' do
         requires :another_input, type: [String, Integer]
       end
       post :action do
+        { message: 'hi' }
       end
 
       add_swagger_documentation
@@ -61,6 +62,7 @@ describe 'Params Multi Types' do
           requires :another_input, type: [String, Integer]
         end
         post :action do
+          { message: 'hi' }
         end
 
         add_swagger_documentation

data/spec/swagger_v2/param_type_spec.rb

@@ -11,12 +11,14 @@ describe 'Params Types' do
         requires :input, type: String
       end
       post :action do
+        { message: 'hi' }
       end
 
       params do
         requires :input, type: String, default: '14', documentation: { type: 'email', default: '42' }
       end
       post :action_with_doc do
+        { message: 'hi' }
       end
 
       add_swagger_documentation
@@ -49,6 +51,7 @@ describe 'Params Types' do
             requires :input, type: String
           end
           post :action do
+            { message: 'hi' }
           end
 
           add_swagger_documentation

data/spec/swagger_v2/param_values_spec.rb

@@ -12,24 +12,28 @@ describe 'Convert values to enum or Range' do
         requires :letter, type: String, values: %w[a b c]
       end
       post :plain_array do
+        { message: 'hi' }
       end
 
       params do
         requires :letter, type: String, values: proc { %w[d e f] }
       end
       post :array_in_proc do
+        { message: 'hi' }
       end
 
       params do
         requires :letter, type: String, values: 'a'..'z'
       end
       post :range_letter do
+        { message: 'hi' }
       end
 
       params do
         requires :integer, type: Integer, values: -5..5
       end
       post :range_integer do
+        { message: 'hi' }
       end
 
       add_swagger_documentation
@@ -107,12 +111,14 @@ describe 'Convert values to enum for float range and not arrays inside a proc',
         requires :letter, type: String, values: proc { 'string' }
       end
       post :non_array_in_proc do
+        { message: 'hi' }
       end
 
       params do
         requires :float, type: Float, values: -5.0..5.0
       end
       post :range_float do
+        { message: 'hi' }
       end
 
       add_swagger_documentation

data/spec/swagger_v2/params_example_spec.rb

@@ -0,0 +1,40 @@
+# 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
+
+      get '/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
+
+    specify do
+      expect(subject['paths']['/endpoint_with_examples']['get']['parameters']).to eql(
+        [
+          { 'in' => 'query', 'name' => 'id', 'type' => 'integer', 'example' => 123, 'format' => 'int32', 'required' => true },
+          { 'in' => 'query', 'name' => 'name', 'type' => 'string', 'example' => 'Person', 'required' => false },
+          { 'in' => 'query', 'name' => 'obj', 'type' => 'Object', 'example' => { 'foo' => 'bar' }, 'required' => false }
+        ]
+      )
+    end
+  end
+end