grape-swagger 0.10.2 → 0.10.4

data/lib/grape-swagger/markdown.rb

@@ -9,7 +9,7 @@ module GrapeSwagger
     ###
     def initialize(adapter)
       adapter = adapter.new if adapter.is_a?(Class)
-      fail(ArgumentError, "The configured markdown adapter should implement the method #{ :markdown }") unless adapter.respond_to? :markdown
+      fail(ArgumentError, "The configured markdown adapter should implement the method #{:markdown}") unless adapter.respond_to? :markdown
       @adapter = adapter
     end
 

data/lib/grape-swagger/version.rb

@@ -1,3 +1,3 @@
 module GrapeSwagger
-  VERSION = '0.10.2'
+  VERSION = '0.10.4'
 end

data/spec/api_description_spec.rb

@@ -12,9 +12,10 @@ describe 'API Description' do
       routes = subject.endpoints.first.routes
       expect(routes.count).to eq 2
       expect(routes.first.route_description).to eq 'Swagger compatible API description'
-      expect(routes.first.route_params).to eq({})
+      expect(routes.first.route_params).to eq('locale' => { desc: 'Locale of API documentation', type: 'Symbol', required: false })
       expect(routes.last.route_description).to eq 'Swagger compatible API description for specific API'
-      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'String', required: true })
+      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'String', required: true },
+                                             'locale' => { desc: 'Locale of API documentation', type: 'Symbol', required: false })
     end
   end
 
@@ -31,10 +32,11 @@ describe 'API Description' do
       routes = subject.endpoints.first.routes
       expect(routes.count).to eq 2
       expect(routes.first.route_description).to eq 'First'
-      expect(routes.first.route_params).to eq(x: 1)
+      expect(routes.first.route_params).to eq(x: 1, 'locale' => { desc: 'Locale of API documentation', type: 'Symbol', required: false })
       expect(routes.first.route_xx).to eq(11)
       expect(routes.last.route_description).to eq 'Second'
-      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'String', required: true }, y: 42)
+      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'String', required: true }, y: 42,
+                                             'locale' => { desc: 'Locale of API documentation', type: 'Symbol', required: false })
       expect(routes.last.route_yy).to eq(4242)
     end
   end

data/spec/array_params_spec.rb

@@ -21,7 +21,7 @@ describe 'Array Params' do
       end
 
       params do
-        optional :raw_array, type: Array[Integer]
+        optional :raw_array, type: Array[Integer], documentation: { is_array: true }
       end
       get :raw_array_integers do
       end
@@ -36,8 +36,8 @@ describe 'Array Params' do
     body = JSON.parse last_response.body
     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 }
+      { 'paramType' => 'form', 'name' => 'a_array[][param_1]', 'description' => '', 'type' => 'integer', 'required' => true, 'allowMultiple' => false, 'format' => 'int32' },
+      { 'paramType' => 'form', 'name' => 'a_array[][param_2]', 'description' => '', 'type' => 'string', 'required' => true, 'allowMultiple' => false }
     ]
   end
 
@@ -47,7 +47,7 @@ describe 'Array Params' do
     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 }
+      { 'paramType' => 'query', 'name' => 'raw_array', 'description' => '', 'type' => 'Array', 'required' => false, 'allowMultiple' => false }
     ]
   end
 
@@ -57,7 +57,7 @@ describe 'Array Params' do
     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' } }
+      { 'paramType' => 'query', 'name' => 'raw_array', 'description' => '', 'type' => 'array', 'required' => false, 'allowMultiple' => false, 'items' => { 'type' => 'integer', 'format' => 'int32' } }
     ]
   end
 end

data/spec/boolean_params_spec.rb

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

data/spec/default_api_spec.rb

@@ -39,9 +39,8 @@ describe 'Default API' do
         end
       end
     end
-
   end
-  context 'with additional option block given to desc', if: GrapeVersion.satisfy?('>= 0.12.0')  do
+  context 'with additional option block given to desc', if: GrapeVersion.satisfy?('>= 0.12.0') do
     def app
       Class.new(Grape::API) do
         format :json

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' => 'number', 'format' => 'float', 'required' => true, 'allowMultiple' => false }
+      { 'paramType' => 'form', 'name' => 'a_float', 'description' => '', 'type' => 'number', 'format' => 'float', 'required' => true, 'allowMultiple' => false }
     ]
   end
 end

data/spec/group_params_spec.rb

@@ -25,7 +25,7 @@ describe 'Group Params' do
     body = JSON.parse last_response.body
     parameters = body['apis'].first['operations'].first['parameters']
     expect(parameters).to eq [
-      { 'paramType' => 'form', 'name' => 'required_group[required_param_1]', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false },
-      { 'paramType' => 'form', 'name' => 'required_group[required_param_2]', 'description' => nil, 'type' => 'string', 'required' => true, 'allowMultiple' => false }]
+      { 'paramType' => 'form', 'name' => 'required_group[required_param_1]', 'description' => '', 'type' => 'string', 'required' => true, 'allowMultiple' => false },
+      { 'paramType' => 'form', 'name' => 'required_group[required_param_2]', 'description' => '', 'type' => 'string', 'required' => true, 'allowMultiple' => false }]
   end
 end

data/spec/hash_params_spec.rb

@@ -24,7 +24,7 @@ describe 'Hash Params' do
 
   it 'declares hash types as object' do
     expect(subject).to eq [
-      { 'paramType' => 'form', 'name' => 'a_hash', 'description' => nil, 'type' => 'object', 'required' => true, 'allowMultiple' => false }
+      { 'paramType' => 'form', 'name' => 'a_hash', 'description' => '', 'type' => 'object', 'required' => true, 'allowMultiple' => false }
     ]
   end
 end

data/spec/i18n_spec.rb

@@ -0,0 +1,364 @@
+require 'spec_helper'
+
+describe 'I18n Default Translation' do
+  module Entities
+    class User < Grape::Entity
+      expose :id, documentation: { type: String }
+      expose :name, documentation: { type: String }
+      expose :email, documentation: { type: String }
+      expose :sign_up_at, documentation: { type: String }
+    end
+
+    class AdminUser < User
+      expose :level, documentation: { type: Integer }
+    end
+
+    class PasswordStrength < Grape::Entity
+      expose :level, documentation: { type: Integer }
+      expose :crack_time, documentation: { type: Float }
+    end
+  end
+
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        optional :locale, type: Symbol
+      end
+      namespace :users do
+        desc nil do
+          success Entities::User
+        end
+        params do
+          optional :sort, type: String
+        end
+        get do
+          []
+        end
+
+        params do
+          requires :id, type: String
+        end
+        route_param :id do
+          desc '' do
+            success Entities::AdminUser
+          end
+          get do
+            {}
+          end
+
+          params do
+            requires :email, type: String
+          end
+          put :email do
+          end
+
+          desc nil do
+            success Entities::PasswordStrength
+          end
+          get :'password/strength' do
+            {}
+          end
+        end
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  def api_translations
+    yaml_en = <<-EOS.strip_heredoc
+      info:
+        title: My Awesome API
+        desc: Some detail information about this API.
+      entities:
+        default:
+          id: Resource identifier
+        user:
+          name: User's real name
+          email: User's login email address
+          sign_up_at: When the user signed up
+        admin_user:
+          level: Which level the admin is
+        password_strength:
+          level: A 0~4 integer indicates `very_weak` to `strong`
+          crack_time: An estimated time for force cracking the password, in seconds
+      params:
+        locale: Used to change locale of endpoint's responding message
+        sort: To specify the order of result list
+      users:
+        desc: Operations about not-disabled users
+        get:
+          desc: Gets a list of users
+          detail: You can control how to sort the results.
+        ':id':
+          params:
+            id: User id
+          get:
+            desc: Finds user by id
+          email:
+            put:
+              desc: Changes a user's email
+              params:
+                email: A new email
+          password:
+            strength:
+              get:
+                desc: Gets the strength estimation of a user's password
+                detail: The estimation is done by a well-known algorithm when he changed his password
+      swagger_doc:
+        desc: Endpoints for API documents
+        get:
+          desc: Gets root API document
+        ':name':
+          get:
+            desc: Gets specific resource API document
+            params:
+              name: Resource name
+    EOS
+
+    YAML.load(yaml_en)
+  end
+
+  context 'swagger_doc' do
+    subject do
+      with_translations :en, api: api_translations do
+        get '/swagger_doc'
+        JSON.parse(last_response.body).deep_symbolize_keys
+      end
+    end
+
+    it 'translates api info' do
+      expect(subject[:info]).to eq(
+        title: 'My Awesome API',
+        description: 'Some detail information about this API.'
+      )
+    end
+
+    it 'translates root namespace description (including swagger_doc)' do
+      expect(subject[:apis]).to eq [
+        { path: '/users.{format}', description: 'Operations about not-disabled users' },
+        { path: '/swagger_doc.{format}', description: 'Endpoints for API documents' }
+      ]
+    end
+  end
+
+  it 'translates endpoint description, notes and params' do
+    result = with_translations :en, api: api_translations do
+      get '/swagger_doc/users'
+      JSON.parse(last_response.body).deep_symbolize_keys
+    end
+
+    api_index = 0
+    expect(result[:apis][api_index][:operations][0]).to include(
+      summary: 'Gets a list of users', notes: 'You can control how to sort the results.'
+    )
+    expect(result[:apis][api_index][:operations][0][:parameters]).to eq [
+      { paramType: 'query', name: 'locale', description: "Used to change locale of endpoint's responding message", type: 'string', required: false, allowMultiple: false },
+      { paramType: 'query', name: 'sort', description: 'To specify the order of result list', type: 'string', required: false, allowMultiple: false }
+    ]
+
+    api_index += 1
+    expect(result[:apis][api_index][:operations][0]).to include(
+      summary: 'Finds user by id', notes: ''
+    )
+    expect(result[:apis][api_index][:operations][0][:parameters]).to eq [
+      { paramType: 'path', name: 'id', description: 'User id', type: 'string', required: true, allowMultiple: false },
+      { paramType: 'query', name: 'locale', description: "Used to change locale of endpoint's responding message", type: 'string', required: false, allowMultiple: false }
+    ]
+
+    api_index += 1
+    expect(result[:apis][api_index][:operations][0]).to include(
+      summary: "Changes a user's email", notes: ''
+    )
+    expect(result[:apis][api_index][:operations][0][:parameters]).to eq [
+      { paramType: 'path', name: 'id', description: 'User id', type: 'string', required: true, allowMultiple: false },
+      { paramType: 'form', name: 'locale', description: "Used to change locale of endpoint's responding message", type: 'string', required: false, allowMultiple: false },
+      { paramType: 'form', name: 'email', description: 'A new email', type: 'string', required: true, allowMultiple: false }
+    ]
+
+    api_index += 1
+    expect(result[:apis][api_index][:operations][0]).to include(
+      summary: "Gets the strength estimation of a user's password", notes: 'The estimation is done by a well-known algorithm when he changed his password'
+    )
+    expect(result[:apis][api_index][:operations][0][:parameters]).to eq [
+      { paramType: 'path', name: 'id', description: 'User id', type: 'string', required: true, allowMultiple: false },
+      { paramType: 'query', name: 'locale', description: "Used to change locale of endpoint's responding message", type: 'string', required: false, allowMultiple: false }
+    ]
+  end
+
+  it 'translates swagger doc endpoints description, notes and params' do
+    result = with_translations :en, api: api_translations do
+      get '/swagger_doc/swagger_doc'
+      JSON.parse(last_response.body).deep_symbolize_keys
+    end
+
+    api_index = 0
+    expect(result[:apis][api_index][:operations][0]).to include(
+      summary: 'Gets root API document'
+    )
+    expect(result[:apis][api_index][:operations][0][:parameters]).to eq [
+      { paramType: 'query', name: 'locale', description: "Used to change locale of endpoint's responding message", type: 'string', required: false, allowMultiple: false }
+    ]
+
+    api_index += 1
+    expect(result[:apis][api_index][:operations][0]).to include(
+      summary: 'Gets specific resource API document'
+    )
+    expect(result[:apis][api_index][:operations][0][:parameters]).to eq [
+      { paramType: 'path', name: 'name', description: 'Resource name', type: 'string', required: true, allowMultiple: false },
+      { paramType: 'query', name: 'locale', description: "Used to change locale of endpoint's responding message", type: 'string', required: false, allowMultiple: false }
+    ]
+  end
+end
+
+describe 'I18n Customized Translation' do
+  def api_translations
+    yaml_en = <<-EOS.strip_heredoc
+      info:
+        title: My Awesome I18n API
+        desc: Some details in English
+      custom:
+        api_info: My Custom Awesome API
+      interpolation: My %{keyword} API
+    EOS
+
+    YAML.load(yaml_en)
+  end
+
+  def extra_translations
+    yaml_en = <<-EOS.strip_heredoc
+      info:
+        title: My Awesome I18n API in Extra Scope
+        desc: Some details in English in Extra Scope
+      custom:
+        api_info: My Custom Awesome API in Extra Scope
+      interpolation: This API supports %{count} languages, and by default it is in %{language}.
+    EOS
+
+    YAML.load(yaml_en)
+  end
+
+  subject do
+    with_translations :en, api: api_translations, extra: extra_translations do
+      get '/swagger_doc'
+      JSON.parse(last_response.body).deep_symbolize_keys
+    end
+  end
+
+  context 'a string' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        add_swagger_documentation info: {
+          title: 'My Plain API', description: 'Boring description', license: 'MIT License'
+        }
+      end
+    end
+
+    it 'became default message when translation missing' do
+      expect(subject[:info]).to eq(
+        title: 'My Awesome I18n API',
+        description: 'Some details in English',
+        license: 'MIT License'
+      )
+    end
+  end
+
+  context 'a symbol' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        add_swagger_documentation info: { title: :'custom.api_info', description: :missing }
+      end
+    end
+
+    it 'acts as custom lookup key' do
+      expect(subject[:info][:title]).to eq 'My Custom Awesome API'
+    end
+
+    it 'can fallback to default key' do
+      expect(subject[:info][:description]).to eq 'Some details in English'
+    end
+  end
+
+  context 'a hash' do
+    context 'using :key and :default' do
+      def app
+        Class.new(Grape::API) do
+          format :json
+          add_swagger_documentation info: {
+            title: { key: :'custom.api_info', default: 'A Demo API' },
+            description: { key: :missing, default: 'No need to say anything more' },
+            license: { key: :license, default: 'MIT License' }
+          }
+        end
+      end
+
+      it 'to define custom lookup key and default message together' do
+        expect(subject[:info]).to eq(
+          title: 'My Custom Awesome API',
+          description: 'Some details in English',
+          license: 'MIT License'
+        )
+      end
+    end
+
+    context 'using :translate with "false"' do
+      def app
+        Class.new(Grape::API) do
+          format :json
+          add_swagger_documentation info: {
+            title: { default: 'A Demo API', translate: false },
+            description: { translate: false }
+          }
+        end
+      end
+
+      it 'to skip translation' do
+        expect(subject[:info]).to eq(
+          title: 'A Demo API'
+        )
+      end
+    end
+
+    context 'using :scope' do
+      def app
+        Class.new(Grape::API) do
+          format :json
+          add_swagger_documentation info: {
+            title: { key: :'custom.api_info', scope: :extra },
+            description: { scope: 'extra' }
+          }
+        end
+      end
+
+      it 'to look up in custom scope' do
+        expect(subject[:info]).to eq(
+          title: 'My Custom Awesome API in Extra Scope',
+          description: 'Some details in English in Extra Scope'
+        )
+      end
+    end
+
+    context 'all other params' do
+      def app
+        Class.new(Grape::API) do
+          format :json
+          add_swagger_documentation info: {
+            title: { key: :interpolation, keyword: 'Best' },
+            description: { key: :interpolation, scope: :extra, count: 2, language: 'English' }
+          }
+        end
+      end
+
+      it 'can be interpolated into the translation' do
+        expect(subject[:info]).to eq(
+          title: 'My Best API',
+          description: 'This API supports 2 languages, and by default it is in English.'
+        )
+      end
+    end
+  end
+end