grape-swagger 0.10.1 → 0.10.2

data/spec/float_api_spec.rb

@@ -24,7 +24,7 @@ describe 'Float Params' do
 
   it 'converts float types' do
     expect(subject).to eq [
-      { 'paramType' => 'form', 'name' => 'a_float', 'description' => nil, 'type' => 'float', 'required' => true, 'allowMultiple' => false }
+      { 'paramType' => 'form', 'name' => 'a_float', 'description' => nil, 'type' => 'number', 'format' => 'float', 'required' => true, 'allowMultiple' => false }
     ]
   end
 end

data/spec/grape-swagger_helper_spec.rb

@@ -24,6 +24,19 @@ describe 'helpers' do
       ]
     end
 
+    it 'parses params as query strings for a GET with an example' do
+      params = {
+        name: { type: 'String', desc: 'A name', required: true, default: 'default api value', documentation: { example: 'default swagger value' } },
+        level: 'max'
+      }
+      path = '/coolness'
+      method = 'GET'
+      expect(subject.parse_params(params, path, method)).to eq [
+        { paramType: 'query', name: :name, description: 'A name', type: 'string', required: true, allowMultiple: false, defaultValue: 'default swagger value' },
+        { paramType: 'query', name: :level, description: '', type: 'string', required: false, allowMultiple: false }
+      ]
+    end
+
     it 'parses params as form for a POST' do
       params = {
         name: { type: 'String', desc: 'A name', required: true },
@@ -132,7 +145,7 @@ describe 'helpers' do
         'XAuthToken' => { description: 'A required header.', required: true, default: 'default' }
       }
       expect(subject.parse_header_params(params)).to eq [
-        { paramType: 'header', name: 'XAuthToken', description: 'A required header.', type: 'String', required: true, defaultValue: 'default' }
+        { paramType: 'header', name: 'XAuthToken', description: 'A required header.', type: 'string', required: true, defaultValue: 'default' }
       ]
     end
   end

data/spec/mounted_target_class_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+
+describe 'docs mounted separately from api' do
+  before :all do
+    class ActualApi < Grape::API
+      desc 'Document root'
+
+      desc 'This gets something.',
+           notes: '_test_'
+      get '/simple' do
+        { bla: 'something' }
+      end
+    end
+
+    class MountedDocs < Grape::API
+      add_swagger_documentation(target_class: ActualApi)
+    end
+
+    class WholeApp < Grape::API
+      mount ActualApi
+      mount MountedDocs
+    end
+  end
+
+  def app
+    WholeApp
+  end
+
+  it 'retrieves docs for actual api class' do
+    get '/swagger_doc.json'
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'info' => {},
+      'produces' => Grape::ContentTypes::CONTENT_TYPES.values.uniq,
+      'apis' => [
+        { 'path' => '/simple.{format}', 'description' => 'Operations about simples' }
+      ]
+    )
+  end
+
+  it 'retrieves docs for endpoint in actual api class' do
+    get '/swagger_doc/simple.json'
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'basePath' => 'http://example.org',
+      'resourcePath' => '/simple',
+      'produces' => Grape::ContentTypes::CONTENT_TYPES.values.uniq,
+      'apis' => [{
+        'path' => '/simple.{format}',
+        'operations' => [{
+          'notes' => '_test_',
+          'summary' => 'This gets something.',
+          'nickname' => 'GET-simple---format-',
+          'method' => 'GET',
+          'parameters' => [],
+          'type' => 'void'
+        }]
+      }]
+    )
+  end
+end

data/spec/non_default_api_spec.rb

@@ -323,7 +323,6 @@ describe 'options: ' do
         'apis' => [{
           'path' => '/abc/v20/something.{format}',
           'operations' => [{
-            'notes' => nil,
             'notes' => '',
             'summary' => 'This gets something.',
             'nickname' => 'GET-abc--version-something---format-',
@@ -497,30 +496,62 @@ describe 'options: ' do
   end
 
   context ':hide_format' do
-    before :all do
-      class HidePathsApi < Grape::API
-        desc 'This gets something.'
-        get '/something' do
-          { bla: 'something' }
+    context 'with no explicit api format specified' do
+      before :all do
+        class HidePathsApi < Grape::API
+          desc 'This gets something.'
+          get '/something' do
+            { bla: 'something' }
+          end
+        end
+
+        class SimpleApiWithHiddenPaths < Grape::API
+          mount HidePathsApi
+          add_swagger_documentation hide_format: true
         end
       end
 
-      class SimpleApiWithHiddenPaths < Grape::API
-        mount ProtectedApi
-        add_swagger_documentation hide_format: true
+      def app
+        SimpleApiWithHiddenPaths
       end
-    end
 
-    def app
-      SimpleApiWithHiddenPaths
+      it 'does not end with format' do
+        get '/swagger_doc/something.json'
+        JSON.parse(last_response.body)['apis'].each do |api|
+          expect(api['path']).to_not end_with '.{format}'
+        end
+      end
     end
 
-    it 'has no formats' do
-      get '/swagger_doc/something.json'
-      JSON.parse(last_response.body)['apis'].each do |api|
-        expect(api['path']).to_not end_with '.{format}'
+    context 'with single api format specified' do
+      before :all do
+        class SingleFormatApi < Grape::API
+          format :json
+          desc 'This gets something.'
+          get '/something' do
+            { bla: 'something' }
+          end
+        end
+
+        class SimpleApiWithSingleFormat < Grape::API
+          mount SingleFormatApi
+          add_swagger_documentation hide_format: true
+        end
+      end
+
+      def app
+        SimpleApiWithSingleFormat
+      end
+
+      it 'does not end with format' do
+        get '/swagger_doc/something.json'
+        JSON.parse(last_response.body)['apis'].each do |api|
+          expect(api['path']).to_not end_with '.{format}'
+          expect(api['path']).to_not end_with '(.json)'
+        end
       end
     end
+
   end
 
   context 'multiple documentations' do

data/spec/param_type_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+describe 'Params Types' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        requires :input, type: String, documentation: { param_type: 'query' }
+      end
+      post :action do
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc/action'
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    body['apis'].first['operations'].first['parameters']
+  end
+
+  it 'reads param type correctly' do
+    expect(subject).to eq [
+      { 'paramType' => 'query', 'name' => 'input', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false }
+    ]
+  end
+
+  describe 'header params' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+
+        desc 'Some API', headers: { 'My-Header' => { required: true, description: 'Set this!' } }
+        params do
+          requires :input, type: String
+        end
+        post :action do
+        end
+
+        add_swagger_documentation
+      end
+    end
+
+    it 'has consistent types' do
+      types = subject.map { |param| param['type'] }
+      expect(types).to eq(%w(string string))
+    end
+  end
+end

data/spec/param_values_spec.rb

@@ -0,0 +1,130 @@
+require 'spec_helper'
+require 'grape_version'
+
+describe 'Convert values to enum or Range' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        requires :letter, type: String, values: %w(a b c)
+      end
+      post :plain_array do
+      end
+
+      params do
+        requires :letter, type: String, values: proc { %w(d e f) }
+      end
+      post :array_in_proc do
+      end
+
+      params do
+        requires :letter, type: String, values: 'a'..'z'
+      end
+      post :range_letter do
+      end
+
+      params do
+        requires :integer, type: Integer, values: -5..5
+      end
+      post :range_integer do
+      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['apis'].first['operations'].first['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 [
+        { 'paramType' => 'form', 'name' => 'letter', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false, '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 [
+        { 'paramType' => 'form', 'name' => 'letter', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false, '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 [
+        { 'paramType' => 'form', 'name' => 'letter', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false }
+      ]
+    end
+
+    subject(:range_integer) { first_parameter_info('range_integer') }
+
+    it 'has integer range values' do
+      expect(range_integer).to eq [
+        { 'paramType' => 'form', 'name' => 'integer', 'description' => nil, 'type' => 'integer', 'required' => true, 'allowMultiple' => false, '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
+
+      params do
+        requires :letter, type: String, values: proc { 'string' }
+      end
+      post :non_array_in_proc do
+      end
+
+      params do
+        requires :float, type: Float, values: -5.0..5.0
+      end
+      post :range_float do
+      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['apis'].first['operations'].first['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 [
+        { 'paramType' => 'form', 'name' => 'letter', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false, 'enum' => '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 [
+        { 'paramType' => 'form', 'name' => 'float', 'description' => nil, 'type' => 'number', 'format' => 'float', 'required' => true, 'allowMultiple' => false }
+      ]
+    end
+  end
+end

data/spec/reference_entity.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+describe 'referenceEntity' do
+  before :all do
+    module MyAPI
+      module Entities
+        class Something < Grape::Entity
+          def self.entity_name
+            'SomethingCustom'
+          end
+
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+        end
+
+        class Kind < Grape::Entity
+          def self.entity_name
+            'KindCustom'
+          end
+
+          expose :title, documentation: { type: 'string', desc: 'Title of the kind.' }
+          expose :something, documentation: { type: Something, desc: 'Something interesting.' }
+        end
+      end
+
+      class ResponseModelApi < Grape::API
+        format :json
+        desc 'This returns kind and something or an error',
+             params: Entities::Kind.documentation.slice(:something),
+             entity: Entities::Kind,
+             http_codes: [
+               [200, 'OK', Entities::Kind]
+             ]
+
+        get '/kind' do
+          kind = OpenStruct.new text: 'kind'
+          present kind, with: Entities::Kind
+        end
+
+        add_swagger_documentation models: [MyAPI::Entities::Something, MyAPI::Entities::Kind]
+      end
+    end
+  end
+
+  def app
+    MyAPI::ResponseModelApi
+  end
+
+  subject do
+    get '/swagger_doc/kind'
+    JSON.parse(last_response.body)
+  end
+
+  it 'should document specified models' do
+    expect(subject['apis'][0]['operations'][0]['parameters']).to eq [{
+      'paramType' => 'query',
+      'name' => 'something',
+      'description' => 'Something interesting.',
+      'type' => 'MySomething',
+      'required' => false,
+      'allowMultiple' => false
+    }]
+
+    expect(subject['models'].keys).to include 'MySomething'
+    expect(subject['models']['MySomething']).to eq(
+      'id' => 'MyAPI::Something',
+      'properties' => {
+        'text' => { 'type' => 'string', 'description' => 'Content of something.' }
+      }
+    )
+
+    expect(subject['models'].keys).to include 'MyKind'
+    expect(subject['models']['MyKind']).to eq(
+      'id' => 'MyKind',
+      'properties' => {
+        'title' => { 'type' => 'string', 'description' => 'Title of the kind.' },
+        'something' => { '$ref' => 'MySomething', 'description' => 'Something interesting.' }
+      }
+    )
+  end
+end