grape-swagger 0.10.2 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5a6996205661a00c64c62bb85fe5c68ea79c0acf
-  data.tar.gz: 446c20aa4754161e0fee6aaff5894af24ec06f76
+  metadata.gz: 4c3b14815684b5e4e77c01b12a1c64029b4cc367
+  data.tar.gz: ecd30bdba3542f6a776c7f94683aab2a2eb32989
 SHA512:
-  metadata.gz: 4968dde338ad1282e6100ec9d7b318c76267346f9048d01d8027065fa7e1e7468ff80038448ebf5184d809512c9b8dbaa5584f7996085b63ed76b5092a7de45c
-  data.tar.gz: 468c21cc9341a54105c7c892432b9e2818b4811bb3add16047b847cac8d6be45beaddfa8b6b41bd08087333b46f1c90317583cf43c3b276cdec1f4b185fdec54
+  metadata.gz: 5b2baa995bd32ba699ea6ffc21fb3816b5a6742a2b3be229df6a47e3cdf85622a52468899c1e5cee3b7f77973fe5dcedfa1330b390a981d09ebca7a47b6bdfbd
+  data.tar.gz: 96a44e9923a0921f2f368f6f128681fa40796c3987fc46a7de54aec2599d00f0de33b42db4f19b5062857155fbf7395f50c25c95f112f43c86db0a525b9e0920

data/.rubocop_todo.yml

@@ -1,55 +1,76 @@
-# This configuration was generated by `rubocop --auto-gen-config`
-# on 2015-04-01 08:13:45 -0400 using RuboCop version 0.27.0.
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2015-08-19 12:17:53 -0400 using RuboCop version 0.33.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 11
+# Offense count: 10
 Metrics/AbcSize:
-  Max: 360
+  Max: 214
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 509
+  Max: 147
 
 # Offense count: 6
 Metrics/CyclomaticComplexity:
-  Max: 102
+  Max: 39
 
-# Offense count: 312
+# Offense count: 304
 # Configuration parameters: AllowURI, URISchemes.
 Metrics/LineLength:
-  Max: 254
+  Max: 242
 
 # Offense count: 21
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 381
+  Max: 170
 
-# Offense count: 5
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ModuleLength:
+  Max: 470
+
+# Offense count: 4
 Metrics/PerceivedComplexity:
-  Max: 105
+  Max: 41
 
 # Offense count: 8
 Style/ClassVars:
-  Enabled: false
+  Exclude:
+    - 'example/api.rb'
+    - 'lib/grape-swagger/doc_methods.rb'
 
-# Offense count: 81
+# Offense count: 90
 Style/Documentation:
   Enabled: false
 
 # Offense count: 2
 Style/DoubleNegation:
-  Enabled: false
+  Exclude:
+    - 'lib/grape-swagger/doc_methods.rb'
 
 # Offense count: 3
 # Configuration parameters: Exclude.
 Style/FileName:
-  Enabled: false
+  Exclude:
+    - 'lib/grape-swagger.rb'
+    - 'spec/grape-swagger_helper_spec.rb'
+    - 'spec/grape-swagger_spec.rb'
 
 # Offense count: 1
 # Configuration parameters: NamePrefix, NamePrefixBlacklist.
 Style/PredicateName:
-  Enabled: false
+  Exclude:
+    - 'lib/grape-swagger/doc_methods.rb'
+
+# Offense count: 4
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles, AllowInnerSlashes.
+Style/RegexpLiteral:
+  Exclude:
+    - 'lib/grape-swagger.rb'
+    - 'lib/grape-swagger/doc_methods.rb'

data/.travis.yml

@@ -17,4 +17,5 @@ env:
   - GRAPE_VERSION=0.11.0
   - GRAPE_VERSION=0.12.0
   - GRAPE_VERSION=0.13.0
+  - GRAPE_VERSION=0.14.0
   - GRAPE_VERSION=HEAD

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+### 0.10.4 (December 7, 2015)
+
+* [#315](https://github.com/ruby-grape/grape-swagger/pull/315): Require `grape-entity` < 0.5.0 - [@dblock](https://github.com/dblock).
+
+### 0.10.3 (December 7, 2015)
+
+* [#292](https://github.com/ruby-grape/grape-swagger/pull/292): Support i18n - [@calfzhou](https://github.com/calfzhou).
+* [#297](https://github.com/ruby-grape/grape-swagger/pull/297): Correct use of documentation param_type - [@fab-girard](https://github.com/fab-girard).
+* [#305](https://github.com/ruby-grape/grape-swagger/pull/305): Speedup by parsing models smarter, not harder - [@jhollinger](https://github.com/jhollinger).
+
 ### 0.10.2 (August 19, 2015)
 
 #### Features

data/README.md

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/grape-swagger.svg)](http://badge.fury.io/rb/grape-swagger)
 [![Build Status](https://travis-ci.org/ruby-grape/grape-swagger.svg?branch=master)](https://travis-ci.org/ruby-grape/grape-swagger)
+[![Dependency Status](https://gemnasium.com/ruby-grape/grape-swagger.svg)](https://gemnasium.com/ruby-grape/grape-swagger)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape-swagger.svg)](https://codeclimate.com/github/ruby-grape/grape-swagger)
 
 ## What is grape-swagger?
@@ -92,6 +93,10 @@ API class name.
 
 Allow markdown in `detail`/`notes`, default is `nil`. (disabled) See below for details.
 
+#### i18n_scope
+
+Translations scope (or array of scopes) default is `:api`. [See below for details](#i18n).
+
 #### hide_format
 
 Don't add `.(format)` to the end of URLs, default is `false`.
@@ -305,7 +310,7 @@ Grape uses the option `default` to set a default value for optional parameters.
 
 ## Grape Entities
 
-Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.
+Add the [grape-entity](https://github.com/ruby-grape/grape-entity) gem to our Gemfile.
 
 The following example exposes statuses. And exposes statuses documentation adding :type and :desc.
 
@@ -511,6 +516,195 @@ get '/', http_codes: [
 end
 ```
 
+## I18n
+
+Grape-swagger supports I18n for most messages of the JSON documentation, including:
+
+* API [info](#info)
+* Namespaces/resources description
+* Endpoints description and detail/notes
+* Params (including headers) description
+* Models/entities description
+
+By default, grape-swagger will lookup translations inside `:api` scope. This can be configured by
+set [`i18n_scope`](#i18n_scope) to a custom scope (or an array of scopes) when calling
+`add_swagger_documentation`.
+
+### Translation and Default Message
+
+To localize your API document, you can add a locale file containing translated messages.
+Grape-swagger will try to look up translation for each message. If a translation cannot be found,
+it will use the message specified in the API code, then default to blank.
+
+Take the following sample API for example:
+
+```ruby
+desc 'Gets all kittens' do
+  detail 'This will expose all the kittens.'
+end
+params do
+  optional :sort
+end
+get :kittens do
+end
+```
+
+To generate I18n documentation, you can add a locale file with translated messages:
+
+```yaml
+api:
+  kittens:
+    get:
+      detail: This will return a full list of kittens, and you can change the way of sorting them.
+      params:
+        sort: Specifies the order of results
+```
+
+The endpoint description in generated API document will be "Gets all kittens" - specified in source
+code - because there is no translation defined. And endpoint details will be overwritten by locale
+message - "This will return a full list of kittens, and you can change the way of sorting them.".
+Parameter `:sort` will have a description from locale file too.
+
+### Default Lookup Keys
+
+The following lookup keys are all within the scope given by `i18n_scope`.
+
+#### API Info
+
+The default lookup key of a field in API info is `info.<field>`, i.e.:
+
+* `info.title` for `:title` field.
+* `info.desc` or `info.description` for `:description` field.
+* `info.contact` for `:contact` field.
+* `info.license` for `:license` field.
+* `info.license_url` for `:license_url` field.
+* `info.terms_of_service_url` for `:terms_of_service_url` field.
+
+#### Namespaces/Resources Description
+
+Grape-swagger will give each root namespace a default description, such as "*Operations about
+users*", where `users` is a namespace (pluralized). But you can change it by provide your own
+message under key `<namespace>.desc` or `<namespace>.description` in your locale file. And the
+namespace itself is available as a variable for interpolation.
+
+### Endpoints Description and Detail/Notes
+
+An endpoint's default lookup key is in format of `<namespace>.<path>.<http_method>`. And if there
+are nested namespaces or multi-level path, all parts will be join by `.`. For example for this
+endpoint:
+
+```ruby
+namespace :users do
+  route_params :id do
+    get :'password/strength' do
+    end
+  end
+end
+```
+
+Its corresponding lookup key will be `users.:id.password.strength.get`, let's say that this is
+the key of this endpoint.
+
+So an endpoint's description message can be given under `<endpoint_key>.desc` or
+`<endpoint_key>.description`. And use `<endpoint_key>.detail` or `<endpoint_key>.notes` for the
+message of its further details.
+
+#### Params Description
+
+The first default key of endpoint parameter's description translation is
+`<endpoint_key>.params.<param_name>`. But considering that some endpoints could usually share a
+same parameter, it will be a little annoyed to duplicate its description message everywhere. So if
+no translation found in the first default key, grape-swagger will try to find all its parent keys.
+Take above endpoint for example, it may have a parameter named `:id`, then the lookup keys are:
+
+1. `users.:id.password.strength.get.params.id`
+1. `users.:id.password.strength.params.id`
+1. `users.:id.password.params.id`
+1. `users.:id.params.id`
+1. `users.params.id`
+1. `params.id`
+
+#### Models/Entities Description
+
+A model class' lookup key is by default its class name, without module part, and underscored. Each
+property's key is then `entities.<class_key>.<property_name>`. When not found, grape-swagger will
+try to check the its ancestors, up to a class whose name is `Entity`.
+
+Say if there is model class `User` inherits `Grape::Entity`, and another model `AdminUser` inherits
+`User`, to translate a property named `:email` of `AdminUser`, the lookup keys are:
+
+1. `entities.admin_user.email`
+1. `entities.user.email`
+1. `entities.default.email`
+
+#### Example Locale File
+
+```yaml
+en:
+  api:
+    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, default is %{default_sort}
+    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
+```
+
+### Customization
+
+The translation can be customized by using different kind/format of message in source code.
+
+* A string or `nil`: It will become the default message when a translation is not defined.
+* A symbol: Looks up translation using the symbol as a key, but will fallback to default key(s).
+* A hash with the following keys:
+  * key: A symbol, defines custom lookup key.
+  * default: A string, defines the default message when translation can not be found.
+  * translate: A boolean (default is `true`), set to `false` to skip translation for this message.
+  * scope: A symbol, or a string, or an array of them. Used to replace the `i18n_scope` config
+    value for a custom lookup scope.
+  * Any other key/value will be sent to the translation function for interpolation.
+
 ## Contributing to grape-swagger
 
 See [CONTRIBUTING](CONTRIBUTING.md).

data/example/config.ru

@@ -2,7 +2,7 @@ require 'rack/cors'
 use Rack::Cors do
   allow do
     origins '*'
-    resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
+    resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options]
   end
 end
 

data/grape-swagger.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
 
   s.add_runtime_dependency 'grape', '>= 0.8.0'
-  s.add_runtime_dependency 'grape-entity'
+  s.add_runtime_dependency 'grape-entity', '< 0.5.0'
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'shoulda'
@@ -21,7 +21,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'bundler'
   s.add_development_dependency 'rack-test'
   s.add_development_dependency 'rack-cors'
-  s.add_development_dependency 'rubocop', '0.27.0'
+  s.add_development_dependency 'rubocop', '0.33.0'
   s.add_development_dependency 'kramdown', '~> 1.4.1'
   s.add_development_dependency 'redcarpet', '~> 3.1.2' unless RUBY_PLATFORM.eql? 'java'
   s.add_development_dependency 'rouge', '~> 1.6.1'

data/lib/grape-swagger.rb

@@ -10,6 +10,7 @@ module Grape
   class API
     class << self
       attr_accessor :combined_routes, :combined_namespaces, :combined_namespace_routes, :combined_namespace_identifiers
+      attr_accessor :endpoint_mapping
 
       def add_swagger_documentation(options = {})
         documentation_class = create_documentation_class
@@ -35,6 +36,7 @@ module Grape
           @target_class.combined_routes[resource] << route
         end
 
+        @target_class.endpoint_mapping = {}
         @target_class.combined_namespaces = {}
         combine_namespaces(@target_class)
 
@@ -60,6 +62,10 @@ module Grape
           # and strip leading slash
           @target_class.combined_namespaces[endpoint.namespace.sub(/^\//, '')] = ns if ns
 
+          endpoint.routes.each do |route|
+            @target_class.endpoint_mapping[route.to_s.sub('(.:format)', '')] = endpoint
+          end
+
           combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
         end
       end
@@ -79,9 +85,9 @@ module Grape
           if namespace.options.key?(:swagger) && namespace.options[:swagger][:nested] == false
             # Namespace shall appear as standalone resource, use specified name or use normalized path as name
             if namespace.options[:swagger].key?(:name)
-              identifier = namespace.options[:swagger][:name].gsub(/ /, '-')
+              identifier = namespace.options[:swagger][:name].tr(' ', '-')
             else
-              identifier = name.gsub(/_/, '-').gsub(/\//, '_')
+              identifier = name.tr('_', '-').gsub(/\//, '_')
             end
             @target_class.combined_namespace_identifiers[identifier] = name
             @target_class.combined_namespace_routes[identifier] = namespace_routes

data/lib/grape-swagger/doc_methods.rb

@@ -1,3 +1,5 @@
+require 'set'
+
 module GrapeSwagger
   module DocMethods
     PRIMITIVE_MAPPINGS = {
@@ -14,11 +16,43 @@ module GrapeSwagger
       @@class_name
     end
 
+    def translate(message, scope, default, params = {})
+      if message.is_a?(String)
+        text = message
+      elsif message.is_a?(Symbol)
+        key = message
+      elsif message.is_a?(Hash)
+        message = message.dup
+        key = message.delete(:key)
+        text = message.delete(:default)
+        skip_translate = !message.delete(:translate) if message.key?(:translate)
+        scope = message.delete(:scope) if message.key?(:scope)
+        params = params.merge(message) unless message.empty?
+      end
+
+      return text if skip_translate
+
+      default = Array(default).dup << (text || '')
+      I18n.t(key, params.merge(scope: scope, default: default))
+    end
+
+    def expand_scope(scope)
+      scopes = []
+      scope = scope.to_s
+      until scope.blank?
+        scopes << scope.to_sym
+        scope = scope.rpartition('.')[0]
+      end
+      scopes << :''
+    end
+
     def as_markdown(description)
       description && @@markdown ? @@markdown.as_markdown(strip_heredoc(description)) : description
     end
 
-    def parse_params(params, path, method)
+    def parse_params(params, path, method, options = {})
+      scope = options[:scope]
+      i18n_keys = expand_scope(options[:key])
       params ||= []
 
       parsed_array_params = parse_array_params(params)
@@ -71,27 +105,29 @@ module GrapeSwagger
         values               = value.is_a?(Hash) ? value[:values] : nil
         enum_or_range_values = parse_enum_or_range_values(values)
 
-        if value.is_a?(Hash) && value.key?(:documentation) && value[:documentation].key?(:param_type)
-          param_type  = value[:documentation][:param_type]
+        if value.is_a?(Hash) && value.key?(:param_type)
+          param_type = value[:param_type]
           if is_array
             items     = { '$ref' => data_type }
             data_type = 'array'
           end
         else
-          param_type  = case
-                        when path.include?(":#{param}")
-                          'path'
-                        when %w(POST PUT PATCH).include?(method)
-                          if is_primitive?(data_type)
-                            'form'
-                          else
-                            'body'
-                          end
-                        else
-                          'query'
+          param_type = case
+                       when path.include?(":#{param}")
+                         'path'
+                       when %w(POST PUT PATCH).include?(method)
+                         if is_primitive?(data_type)
+                           'form'
+                         else
+                           'body'
+                         end
+                       else
+                         'query'
                         end
         end
         name          = (value.is_a?(Hash) && value[:full_name]) || param
+        description = translate(description, scope,
+                                i18n_keys.map { |key| :"#{key}.params.#{name}" })
 
         parsed_params = {
           paramType:     param_type,
@@ -99,14 +135,14 @@ module GrapeSwagger
           description:   as_markdown(description),
           type:          data_type,
           required:      required,
-          allowMultiple: is_array
+          allowMultiple: is_array && data_type != 'array' && %w(query header path).include?(param_type)
         }
 
         if PRIMITIVE_MAPPINGS.key?(data_type)
           parsed_params[:type], parsed_params[:format] = PRIMITIVE_MAPPINGS[data_type]
         end
 
-        parsed_params[:items]  = items   if items.present?
+        parsed_params[:items] = items if items.present?
 
         parsed_params[:defaultValue] = example if example
         if default_value && example.blank?
@@ -130,18 +166,22 @@ module GrapeSwagger
       content_types.uniq
     end
 
-    def parse_info(info)
+    def parse_info(info, options = {})
+      scope = options[:scope]
+
       {
-        contact:            info[:contact],
-        description:        as_markdown(info[:description]),
-        license:            info[:license],
-        licenseUrl:         info[:license_url],
-        termsOfServiceUrl:  info[:terms_of_service_url],
-        title:              info[:title]
+        contact:            translate(info[:contact], scope, :'info.contact'),
+        description:        as_markdown(translate(info[:description], scope, [:'info.desc', :'info.description'])),
+        license:            translate(info[:license], scope, :'info.license'),
+        licenseUrl:         translate(info[:license_url], scope, :'info.license_url'),
+        termsOfServiceUrl:  translate(info[:terms_of_service_url], scope, :'info.terms_of_service_url'),
+        title:              translate(info[:title], scope, :'info.title')
       }.delete_if { |_, value| value.blank? }
     end
 
-    def parse_header_params(params)
+    def parse_header_params(params, options = {})
+      scope = options[:scope]
+      i18n_keys = expand_scope(options[:key])
       params ||= []
 
       params.map do |param, value|
@@ -151,6 +191,9 @@ module GrapeSwagger
         default_value = value.is_a?(Hash) ? value[:default] : nil
         param_type    = 'header'
 
+        description = translate(description, scope,
+                                i18n_keys.map { |key| :"#{key}.params.#{param}" })
+
         parsed_params = {
           paramType:    param_type,
           name:         param,
@@ -191,13 +234,22 @@ module GrapeSwagger
       end
     end
 
-    def parse_entity_models(models)
+    def parse_entity_models(models, options = {})
+      scope = options[:scope]
       result = {}
       models.each do |model|
         name       = (model.instance_variable_get(:@root) || parse_entity_name(model))
         properties = {}
         required   = []
 
+        i18n_keys = []
+        klass = model
+        until %w(entity object).include? klass.name.demodulize.underscore
+          i18n_keys << klass.name.demodulize.underscore.to_sym
+          klass = klass.superclass
+        end
+        i18n_keys << :default
+
         model.documentation.each do |property_name, property_info|
           p = property_info.dup
 
@@ -219,7 +271,9 @@ module GrapeSwagger
 
           # rename Grape Entity's "desc" to "description"
           property_description = p.delete(:desc)
-          p[:description] = property_description if property_description
+          property_description = translate(property_description, scope,
+                                           i18n_keys.map { |key| :"entities.#{key}.#{property_name}" })
+          p[:description] = property_description unless property_description.blank?
 
           # rename Grape's 'values' to 'enum'
           select_values = p.delete(:values)
@@ -324,6 +378,7 @@ module GrapeSwagger
         base_path: nil,
         api_version: '0.1',
         markdown: nil,
+        i18n_scope: :api,
         hide_documentation_path: false,
         hide_format: false,
         format: nil,
@@ -339,7 +394,7 @@ module GrapeSwagger
 
       target_class     = options[:target_class]
       @@mount_path     = options[:mount_path]
-      @@class_name     = options[:class_name] || options[:mount_path].gsub('/', '')
+      @@class_name     = options[:class_name] || options[:mount_path].delete('/')
       @@markdown       = options[:markdown] ? GrapeSwagger::Markdown.new(options[:markdown]) : nil
       @@hide_format    = options[:hide_format]
       api_version      = options[:api_version]
@@ -349,6 +404,7 @@ module GrapeSwagger
       api_doc          = options[:api_documentation].dup
       specific_api_doc = options[:specific_api_documentation].dup
       @@models         = options[:models] || []
+      i18n_scope       = options[:i18n_scope]
 
       @@hide_documentation_path = options[:hide_documentation_path]
 
@@ -361,7 +417,11 @@ module GrapeSwagger
       @@documentation_class = self
 
       desc api_doc.delete(:desc), api_doc
+      params do
+        optional :locale, type: Symbol, desc: 'Locale of API documentation'
+      end
       get @@mount_path do
+        I18n.locale = params[:locale] || I18n.default_locale
         header['Access-Control-Allow-Origin']   = '*'
         header['Access-Control-Request-Method'] = '*'
 
@@ -375,14 +435,23 @@ module GrapeSwagger
         namespace_routes_array = namespace_routes.keys.map do |local_route|
           next if namespace_routes[local_route].map(&:route_hidden).all? { |value| value.respond_to?(:call) ? value.call : value }
 
-          url_format  = '.{format}' unless @@hide_format
+          url_format = '.{format}' unless @@hide_format
+          url_locale = "?locale=#{params[:locale]}" unless params[:locale].blank?
 
           original_namespace_name = target_class.combined_namespace_identifiers.key?(local_route) ? target_class.combined_namespace_identifiers[local_route] : local_route
           description = namespaces[original_namespace_name] && namespaces[original_namespace_name].options[:desc]
           description ||= "Operations about #{original_namespace_name.pluralize}"
+          description = @@documentation_class.translate(
+            description, i18n_scope,
+            [
+              :"#{original_namespace_name}.desc",
+              :"#{original_namespace_name}.description"
+            ],
+            namespace: original_namespace_name.pluralize
+          )
 
           {
-            path: "/#{local_route}#{url_format}",
+            path: "/#{local_route}#{url_format}#{url_locale}",
             description: description
           }
         end.compact
@@ -392,7 +461,7 @@ module GrapeSwagger
           swaggerVersion: '1.2',
           produces:       @@documentation_class.content_types_for(target_class),
           apis:           namespace_routes_array,
-          info:           @@documentation_class.parse_info(extra_info)
+          info:           @@documentation_class.parse_info(extra_info, scope: i18n_scope)
         }
 
         output[:authorizations] = authorizations unless authorizations.nil? || authorizations.empty?
@@ -403,13 +472,15 @@ module GrapeSwagger
       desc specific_api_doc.delete(:desc), { params:
         specific_api_doc.delete(:params) || {} }.merge(specific_api_doc)
       params do
+        optional :locale, type: Symbol, desc: 'Locale of API documentation'
         requires :name, type: String, desc: 'Resource name of mounted API'
       end
       get "#{@@mount_path}/:name" do
+        I18n.locale = params[:locale] || I18n.default_locale
         header['Access-Control-Allow-Origin']   = '*'
         header['Access-Control-Request-Method'] = '*'
 
-        models = []
+        models = Set.new(@@models.dup)
         routes = target_class.combined_namespace_routes[params[:name]]
         error!('Not Found', 404) unless routes
 
@@ -427,22 +498,33 @@ module GrapeSwagger
 
         ops.each do |path, op_routes|
           operations = op_routes.map do |route|
-            notes       = @@documentation_class.as_markdown(route.route_detail || route.route_notes)
+            endpoint = target_class.endpoint_mapping[route.to_s.sub('(.:format)', '')]
+            endpoint_path = endpoint.options[:path] unless endpoint.nil?
+            i18n_key = [route.route_namespace, endpoint_path, route.route_method.downcase].flatten.join('/')
+            i18n_key = i18n_key.split('/').reject(&:empty?).join('.')
+
+            summary = @@documentation_class.translate(
+              route.route_description, i18n_scope,
+              [:"#{i18n_key}.desc", :"#{i18n_key}.description"]
+            )
+            notes = @@documentation_class.translate(
+              route.route_detail || route.route_notes, i18n_scope,
+              [:"#{i18n_key}.detail", :"#{i18n_key}.notes"]
+            )
+            notes       = @@documentation_class.as_markdown(notes)
 
             http_codes  = @@documentation_class.parse_http_codes(route.route_http_codes, models)
 
-            models |= @@models if @@models.present?
-
-            models |= Array(route.route_entity) if route.route_entity.present?
-
-            models = @@documentation_class.models_with_included_presenters(models.flatten.compact)
+            models.merge(Array(route.route_entity)) if route.route_entity.present?
 
             operation = {
               notes: notes.to_s,
-              summary: route.route_description || '',
+              summary: summary,
               nickname: route.route_nickname || (route.route_method + route.route_path.gsub(/[\/:\(\)\.]/, '-')),
               method: route.route_method,
-              parameters: @@documentation_class.parse_header_params(route.route_headers) + @@documentation_class.parse_params(route.route_params, route.route_path, route.route_method),
+              parameters: @@documentation_class.parse_header_params(route.route_headers, scope: i18n_scope, key: i18n_key) +
+                          @@documentation_class.parse_params(route.route_params, route.route_path, route.route_method,
+                                                             scope: i18n_scope, key: i18n_key),
               type: route.route_is_array ? 'array' : 'void'
             }
             operation[:authorizations] = route.route_authorizations unless route.route_authorizations.nil? || route.route_authorizations.empty?
@@ -469,6 +551,8 @@ module GrapeSwagger
           }
         end
 
+        models = @@documentation_class.models_with_included_presenters(models.to_a.flatten.compact)
+
         # use custom resource naming if available
         if target_class.combined_namespace_identifiers.key? params[:name]
           resource_path = target_class.combined_namespace_identifiers[params[:name]]
@@ -485,7 +569,7 @@ module GrapeSwagger
 
         base_path                        = @@documentation_class.parse_base_path(options[:base_path], request)
         api_description[:basePath]       = base_path if base_path && base_path.size > 0 && root_base_path != false
-        api_description[:models]         = @@documentation_class.parse_entity_models(models) unless models.empty?
+        api_description[:models]         = @@documentation_class.parse_entity_models(models, scope: i18n_scope) unless models.empty?
         api_description[:authorizations] = authorizations if authorizations
 
         api_description