grape-swagger 1.1.0 → 1.4.0

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/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_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

@@ -11,6 +11,7 @@ describe 'Boolean Params' do
         requires :a_boolean, type: Grape::API::Boolean
       end
       post :splines do
+        { message: 'hi' }
       end
 
       add_swagger_documentation

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

data/spec/swagger_v2/reference_entity_spec.rb

@@ -22,6 +22,20 @@ describe 'referenceEntity' do
           expose :title, documentation: { type: 'string', desc: 'Title of the kind.' }
           expose :something, documentation: { type: Something, desc: 'Something interesting.' }
         end
+
+        class Base < Grape::Entity
+          def self.entity_name
+            parts = to_s.split('::')
+
+            "MyAPI::#{parts.last}"
+          end
+
+          expose :title, documentation: { type: 'string', desc: 'Title of the parent.' }
+        end
+
+        class Child < Base
+          expose :child, documentation: { type: 'string', desc: 'Child property.' }
+        end
       end
 
       class ResponseModelApi < Grape::API
@@ -40,6 +54,16 @@ describe 'referenceEntity' do
           present kind, with: Entities::Kind
         end
 
+        desc 'This returns a child entity',
+             entity: Entities::Child,
+             http_codes: [
+               { code: 200, message: 'OK', model: Entities::Child }
+             ]
+        get '/child' do
+          child = OpenStruct.new text: 'child'
+          present child, with: Entities::Child
+        end
+
         add_swagger_documentation # models: [MyAPI::Entities::Something, MyAPI::Entities::Kind]
       end
     end
@@ -49,36 +73,57 @@ describe 'referenceEntity' do
     MyAPI::ResponseModelApi
   end
 
-  subject do
-    get '/swagger_doc/kind'
-    JSON.parse(last_response.body)
+  describe 'kind' do
+    subject do
+      get '/swagger_doc/kind'
+      JSON.parse(last_response.body)
+    end
+
+    it 'should document specified models' do
+      expect(subject['paths']['/kind']['get']['parameters']).to eq [{
+        'in' => 'query',
+        'name' => 'something',
+        'description' => 'Something interesting.',
+        'type' => 'SomethingCustom',
+        'required' => false
+      }]
+
+      expect(subject['definitions'].keys).to include 'SomethingCustom'
+      expect(subject['definitions']['SomethingCustom']).to eq(
+        'type' => 'object', 'properties' => { 'text' => { 'type' => 'string', 'description' => 'Content of something.' } }
+      )
+
+      expect(subject['definitions'].keys).to include 'KindCustom'
+      expect(subject['definitions']['KindCustom']).to eq(
+        'type' => 'object',
+        'properties' => {
+          'title' => { 'type' => 'string', 'description' => 'Title of the kind.' },
+          'something' => {
+            '$ref' => '#/definitions/SomethingCustom',
+            'description' => 'Something interesting.'
+          }
+        },
+        'description' => 'KindCustom model'
+      )
+    end
   end
 
-  it 'should document specified models' do
-    expect(subject['paths']['/kind']['get']['parameters']).to eq [{
-      'in' => 'query',
-      'name' => 'something',
-      'description' => 'Something interesting.',
-      'type' => 'SomethingCustom',
-      'required' => false
-    }]
-
-    expect(subject['definitions'].keys).to include 'SomethingCustom'
-    expect(subject['definitions']['SomethingCustom']).to eq(
-      'type' => 'object', 'properties' => { 'text' => { 'type' => 'string', 'description' => 'Content of something.' } }
-    )
-
-    expect(subject['definitions'].keys).to include 'KindCustom'
-    expect(subject['definitions']['KindCustom']).to eq(
-      'type' => 'object',
-      'properties' => {
-        'title' => { 'type' => 'string', 'description' => 'Title of the kind.' },
-        'something' => {
-          '$ref' => '#/definitions/SomethingCustom',
-          'description' => 'Something interesting.'
-        }
-      },
-      'description' => 'This returns kind and something or an error'
-    )
+  describe 'child' do
+    subject do
+      get '/swagger_doc/child'
+      JSON.parse(last_response.body)
+    end
+
+    it 'should document specified models' do
+      expect(subject['definitions'].keys).to include 'MyAPI::Child'
+      expect(subject['definitions']['MyAPI::Child']).to eq(
+        'type' => 'object',
+        'properties' => {
+          'title' => { 'type' => 'string', 'description' => 'Title of the parent.' },
+          'child' => { 'type' => 'string', 'description' => 'Child property.' }
+        },
+        'description' => 'MyAPI::Child model'
+      )
+    end
   end
 end