grape-swagger 0.10.0 → 0.10.2

data/spec/api_global_models_spec.rb

@@ -43,13 +43,13 @@ describe 'Global Models' do
     get '/swagger_doc/thing.json'
     json = JSON.parse(last_response.body)
     expect(json['models']).to eq(
-        'Some::Thing' => {
-          'id' => 'Some::Thing',
-          'properties' => {
-            'text' => { 'type' => 'string', 'description' => 'Content of something.' },
-            'name' => { 'type' => 'string', 'description' => 'Name of something.' }
-          }
-        })
+      'Some::Thing' => {
+        'id' => 'Some::Thing',
+        'properties' => {
+          'text' => { 'type' => 'string', 'description' => 'Content of something.' },
+          'name' => { 'type' => 'string', 'description' => 'Name of something.' }
+        }
+      })
   end
 
   it 'uses global models and route endpoint specific entities together' do
@@ -57,21 +57,21 @@ describe 'Global Models' do
     json = JSON.parse(last_response.body)
 
     expect(json['models']).to include(
-                                  'Some::Thing' => {
-                                    'id' => 'Some::Thing',
-                                    'properties' => {
-                                      'text' => { 'type' => 'string', 'description' => 'Content of something.' },
-                                      'name' => { 'type' => 'string', 'description' => 'Name of something.' }
-                                    }
-                                  })
+      'Some::Thing' => {
+        'id' => 'Some::Thing',
+        'properties' => {
+          'text' => { 'type' => 'string', 'description' => 'Content of something.' },
+          'name' => { 'type' => 'string', 'description' => 'Name of something.' }
+        }
+      })
 
     expect(json['models']).to include(
-                                  'Some::CombinedThing' => {
-                                    'id' => 'Some::CombinedThing',
-                                    'properties' => {
-                                      'text' => { 'type' => 'string', 'description' => 'Content of something.' },
-                                      'created_at' => { 'type' => 'dateTime', 'description' => 'Creation of something.' }
-                                    }
-                                  })
+      'Some::CombinedThing' => {
+        'id' => 'Some::CombinedThing',
+        'properties' => {
+          'text' => { 'type' => 'string', 'description' => 'Content of something.' },
+          'created_at' => { 'type' => 'string', 'format' => 'date-time', 'description' => 'Creation of something.' }
+        }
+      })
   end
 end

data/spec/api_models_spec.rb

@@ -94,6 +94,13 @@ describe 'API Models' do
     end
   end
 
+  module Entities
+    class ThingWithRoot < Grape::Entity
+      root 'things', 'thing'
+      expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+    end
+  end
+
   def app
     Class.new(Grape::API) do
       format :json
@@ -149,6 +156,12 @@ describe 'API Models' do
         present result, with: Entities::QueryResult
       end
 
+      desc 'This gets thing_with_root.', entity: Entities::ThingWithRoot
+      get '/thing_with_root' do
+        thing = OpenStruct.new text: 'thing'
+        present thing, with: Entities::ThingWithRoot
+      end
+
       add_swagger_documentation
     end
   end
@@ -177,6 +190,7 @@ describe 'API Models' do
         { 'path' => '/aliasedthing.{format}', 'description' => 'Operations about aliasedthings' },
         { 'path' => '/nesting.{format}', 'description' => 'Operations about nestings' },
         { 'path' => '/multiple_entities.{format}', 'description' => 'Operations about multiple_entities' },
+        { 'path' => '/thing_with_root.{format}', 'description' => 'Operations about thing_with_roots' },
         { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
       ]
     end
@@ -213,68 +227,68 @@ describe 'API Models' do
                                                          },
                                                          'required' => ['parts']
 
-                                                 )
+                                                        )
 
     expect(result['models']['ComposedOf']).to include(
-                                                        'id' => 'ComposedOf',
-                                                        'properties' => {
-                                                          'part_text' => {
-                                                            'type' => 'string',
-                                                            'description' => 'Content of composedof.'
-                                                          }
-                                                        }
-                                                      )
+      'id' => 'ComposedOf',
+      'properties' => {
+        'part_text' => {
+          'type' => 'string',
+          'description' => 'Content of composedof.'
+        }
+      }
+    )
 
     expect(result['models']['composed']).to include(
-                                                      'id' => 'composed',
-                                                      'properties' => {
-                                                        'part_text' => {
-                                                          'type' => 'string',
-                                                          'description' => 'Content of composedof else.'
-                                                        }
-
-                                                      }
-                                                    )
+      'id' => 'composed',
+      'properties' => {
+        'part_text' => {
+          'type' => 'string',
+          'description' => 'Content of composedof else.'
+        }
+
+      }
+    )
   end
 
   it 'includes enum values in params and documentation.' do
     get '/swagger_doc/enum_description_in_entity'
     result = JSON.parse(last_response.body)
     expect(result['models']['EnumValues']).to eq(
-                                                  'id' => 'EnumValues',
-                                                  'properties' => {
-                                                    'gender' => { 'type' => 'string', 'description' => 'Content of something.', 'enum' => %w(Male Female) },
-                                                    'number' => { 'type' => 'integer', 'description' => 'Content of something.', 'enum' => [1, 2] }
-                                                  }
-                                              )
+      'id' => 'EnumValues',
+      'properties' => {
+        'gender' => { 'type' => 'string', 'description' => 'Content of something.', 'enum' => %w(Male Female) },
+        'number' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'Content of something.', 'enum' => [1, 2] }
+      }
+    )
 
     expect(result['apis'][0]['operations'][0]).to include(
-                                                      'parameters' =>
-                                                         [
-                                                           { 'paramType' => 'query', 'name' => 'gender', 'description' => 'Content of something.', 'type' => 'string', 'required' => false, 'allowMultiple' => false, 'enum' => %w(Male Female) },
-                                                           { 'paramType' => 'query', 'name' => 'number', 'description' => 'Content of something.', 'type' => 'integer', 'required' => false, 'allowMultiple' => false, 'format' => 'int32', 'enum' => [1, 2] }
-                                                         ],
-                                                      'type' => 'EnumValues'
-                                                  )
+      'parameters' =>
+         [
+           { 'paramType' => 'query', 'name' => 'gender', 'description' => 'Content of something.', 'type' => 'string', 'required' => false, 'allowMultiple' => false, 'enum' => %w(Male Female) },
+           { 'paramType' => 'query', 'name' => 'number', 'description' => 'Content of something.', 'type' => 'integer', 'required' => false, 'allowMultiple' => false, 'format' => 'int32', 'enum' => [1, 2] }
+         ],
+      'type' => 'EnumValues'
+    )
   end
 
   it 'includes referenced models in those with aliased references.' do
     get '/swagger_doc/aliasedthing'
     result = JSON.parse(last_response.body)
     expect(result['models']['AliasedThing']).to eq(
-                                                    'id' => 'AliasedThing',
-                                                    'properties' => {
-                                                      'post' => { '$ref' => 'Something', 'description' => 'Reference to something.' }
-                                                    }
-                                                )
+      'id' => 'AliasedThing',
+      'properties' => {
+        'post' => { '$ref' => 'Something', 'description' => 'Reference to something.' }
+      }
+    )
 
     expect(result['models']['Something']).to eq(
-                                                 'id' => 'Something',
-                                                 'properties' => {
-                                                   'text' => { 'type' => 'string', 'description' => 'Content of something.' },
-                                                   'links' => { 'type' => 'array', 'items' => { '$ref' => 'link' } }
-                                                 }
-                                             )
+      'id' => 'Something',
+      'properties' => {
+        'text' => { 'type' => 'string', 'description' => 'Content of something.' },
+        'links' => { 'type' => 'array', 'items' => { '$ref' => 'link' } }
+      }
+    )
   end
 
   it 'includes all entities with four levels of nesting' do
@@ -290,4 +304,10 @@ describe 'API Models' do
 
     expect(result['models']).to include('QueryInput', 'QueryInputElement', 'QueryResult')
   end
+
+  it 'includes an id equal to the model name' do
+    get '/swagger_doc/thing_with_root'
+    result = JSON.parse(last_response.body)
+    expect(result['models']['thing']['id']).to eq('thing')
+  end
 end

data/spec/api_paths_spec.rb

@@ -62,3 +62,67 @@ describe 'simple api with prefix' do
     end
   end
 end
+
+describe 'simple api with partially same path as docs mount and hidden doc path' do
+  before :all do
+    class SamePathApi < Grape::API
+      desc 'This gets the documents'
+      get '/documents' do
+        { test: 'something' }
+      end
+
+      desc 'This gets the doc types'
+      get '/doc-types' do
+        { test: 'something' }
+      end
+    end
+
+    class SimpleSamePathApi < Grape::API
+      mount SamePathApi
+      add_swagger_documentation(
+        mount_path: '/doc',
+        hide_documentation_path: true
+      )
+    end
+  end
+
+  def app
+    SimpleSamePathApi
+  end
+
+  it 'retrieves swagger-documentation on /doc that contains documents' do
+    get '/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' => '/documents.{format}', 'description' => 'Operations about documents' },
+        { 'path' => '/doc-types.{format}', 'description' => 'Operations about doc-types' }
+      ]
+    )
+  end
+
+  it 'retrieves the documentation for apis' do
+    get '/doc/documents.json'
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'basePath' => 'http://example.org',
+      'resourcePath' => '/documents',
+      'produces' => Grape::ContentTypes::CONTENT_TYPES.values.uniq,
+      'apis' => [{
+        'path' => '/documents.{format}',
+        'operations' => [{
+          'notes' => '',
+          'summary' => 'This gets the documents',
+          'nickname' => 'GET-documents---format-',
+          'method' => 'GET',
+          'parameters' => [],
+          'type' => 'void'
+        }]
+      }]
+    )
+  end
+end

data/spec/api_with_nil_types.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe 'API with minimally documented models' do
+  def app
+    entity_klass = Class.new do
+      def self.exposures
+        {}
+      end
+
+      def self.documentation
+        {
+          bar: { type: String },
+          foo: {}
+        }
+      end
+
+      def self.entity_name
+        'Foo'
+      end
+    end
+
+    Class.new(Grape::API) do
+      format :json
+
+      get :foo do
+      end
+
+      add_swagger_documentation \
+        format: :json,
+        models: [Class.new(entity_klass)]
+    end
+  end
+
+  subject do
+    get '/swagger_doc/foo'
+    JSON.parse(last_response.body)['models']
+  end
+
+  it 'returns model' do
+    expect(subject).to eq(
+      'Foo' => {
+        'id' => 'Foo',
+        'properties' => {
+          'bar' => { 'type' => 'string' },
+          'foo' => { '$ref' => nil }
+        }
+      }
+    )
+  end
+end

data/spec/api_with_prefix_and_namespace_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe 'API with Prefix and Namespace' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+      prefix 'api'
+
+      namespace :status do
+        desc 'Retrieve status.'
+        get do
+        end
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/api/swagger_doc'
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    body['apis']
+  end
+
+  it 'gets array types' do
+    expect(subject).to eq([
+      { 'path' => '/status.{format}', 'description' => 'Operations about statuses' },
+      { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
+    ])
+  end
+end

data/spec/api_with_standalone_namespace_spec.rb

@@ -47,14 +47,14 @@ describe 'Standalone namespace API' do
 
       it 'that contains all api paths' do
         expect(json_body['apis']).to eq(
-                                         [
-                                           { 'path' => '/store.{format}', 'description' => 'Operations about stores' },
-                                           { 'path' => '/store_orders.{format}', 'description' => 'Operations about store/orders' },
-                                           { 'path' => '/store_orders_actions2.{format}', 'description' => 'Operations about store/orders/actions2s' },
-                                           { 'path' => '/specific-store-orders.{format}', 'description' => 'Operations about store/:store_id/orders' },
-                                           { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
-                                         ]
-                                     )
+          [
+            { 'path' => '/store.{format}', 'description' => 'Operations about stores' },
+            { 'path' => '/store_orders.{format}', 'description' => 'Operations about store/orders' },
+            { 'path' => '/store_orders_actions2.{format}', 'description' => 'Operations about store/orders/actions2s' },
+            { 'path' => '/specific-store-orders.{format}', 'description' => 'Operations about store/:store_id/orders' },
+            { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
+          ]
+        )
       end
     end
 
@@ -152,14 +152,14 @@ describe 'Standalone namespace API' do
 
       it 'that contains all api paths' do
         expect(json_body['apis']).to eq(
-                                         [
-                                           { 'path' => '/store.{format}', 'description' => 'Operations about stores' },
-                                           { 'path' => '/store_orders.{format}', 'description' => 'Operations about store/orders' },
-                                           { 'path' => '/store_orders_actions2.{format}', 'description' => 'Operations about store/orders/actions2s' },
-                                           { 'path' => '/specific-store-orders.{format}', 'description' => 'Operations about store/:store_id/orders' },
-                                           { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
-                                         ]
-                                     )
+          [
+            { 'path' => '/store.{format}', 'description' => 'Operations about stores' },
+            { 'path' => '/store_orders.{format}', 'description' => 'Operations about store/orders' },
+            { 'path' => '/store_orders_actions2.{format}', 'description' => 'Operations about store/orders/actions2s' },
+            { 'path' => '/specific-store-orders.{format}', 'description' => 'Operations about store/:store_id/orders' },
+            { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
+          ]
+        )
       end
     end
 

data/spec/array_entity_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe 'Array Entity' do
+  before :all do
+    class Something < Grape::Entity
+      expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+    end
+  end
+
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'This returns something or an error',
+           is_array: true,
+           entity: Something
+      post :action do
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc/action'
+    JSON.parse(last_response.body)
+  end
+
+  it 'reads param type correctly' do
+    expect(subject['models'].keys).to include 'Something'
+    expect(subject['apis'][0]['operations'][0]['type']).to eq('array')
+    expect(subject['apis'][0]['operations'][0]['items']).to eq('$ref' => 'Something')
+  end
+end

data/spec/array_params_spec.rb

@@ -14,21 +14,50 @@ describe 'Array Params' do
       post :splines do
       end
 
+      params do
+        optional :raw_array, type: Array
+      end
+      get :raw_array_splines do
+      end
+
+      params do
+        optional :raw_array, type: Array[Integer]
+      end
+      get :raw_array_integers do
+      end
+
       add_swagger_documentation
     end
   end
 
-  subject do
+  it 'gets array types' do
     get '/swagger_doc/splines'
     expect(last_response.status).to eq 200
     body = JSON.parse last_response.body
-    body['apis'].first['operations'].first['parameters']
-  end
-
-  it 'gets array types' do
-    expect(subject).to eq [
+    parameters = body['apis'].first['operations'].first['parameters']
+    expect(parameters).to eq [
       { 'paramType' => 'form', 'name' => 'a_array[][param_1]', 'description' => nil, 'type' => 'integer', 'required' => true, 'allowMultiple' => false, 'format' => 'int32' },
       { 'paramType' => 'form', 'name' => 'a_array[][param_2]', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false }
     ]
   end
+
+  it 'get raw array type' do
+    get '/swagger_doc/raw_array_splines'
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    parameters = body['apis'].first['operations'].first['parameters']
+    expect(parameters).to eq [
+      { 'paramType' => 'query', 'name' => 'raw_array', 'description' => nil, 'type' => 'Array', 'required' => false, 'allowMultiple' => false }
+    ]
+  end
+
+  it 'get raw array integer' do
+    get '/swagger_doc/raw_array_integers'
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    parameters = body['apis'].first['operations'].first['parameters']
+    expect(parameters).to eq [
+      { 'paramType' => 'query', 'name' => 'raw_array', 'description' => nil, 'type' => 'array', 'required' => false, 'allowMultiple' => false, 'items' => { 'type' => 'integer', 'format' => 'int32' } }
+    ]
+  end
 end

data/spec/default_api_spec.rb

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require 'grape_version'
 
 describe 'Default API' do
   context 'with no additional options' do
@@ -38,6 +39,47 @@ describe 'Default API' do
         end
       end
     end
+
+  end
+  context 'with additional option block given to desc', if: GrapeVersion.satisfy?('>= 0.12.0')  do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        desc 'This gets something.' do
+          detail 'more details about the endpoint'
+        end
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation
+      end
+    end
+
+    subject do
+      get '/swagger_doc/something'
+      JSON.parse(last_response.body)
+    end
+
+    it 'documents endpoint' do
+      expect(subject).to eq(
+        'apiVersion'     => '0.1',
+        'swaggerVersion' => '1.2',
+        'basePath'       => 'http://example.org',
+        'produces'       => ['application/json'],
+        'resourcePath'   => '/something',
+        'apis'           => [{
+          'path' => '/something.{format}',
+          'operations' => [{
+            'notes'      => 'more details about the endpoint',
+            'summary'    => 'This gets something.',
+            'nickname'   => 'GET-something--json-',
+            'method'     => 'GET',
+            'parameters' => [],
+            'type'       => 'void'
+          }]
+        }]
+      )
+    end
   end
 
   context 'with additional info' do

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