grape-swagger 0.7.2 → 0.8.0

data/RELEASING.md

@@ -0,0 +1,80 @@
+# Releasing Grape-Swagger
+
+There're no particular rules about when to release grape-swagger. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
+
+### Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+rake
+```
+
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/tim-vandecasteele/grape-swagger) for all supported platforms.
+
+Increment the version, modify [lib/grape-swagger/version.rb](lib/grape-swagger/version.rb).
+
+*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.7.1` to `0.7.2`).
+*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.7.1` to `0.8.0`).
+
+Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+
+```
+### 0.7.2 (February 6, 2014)
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/grape-swagger/version.rb
+git commit -m "Preparing for release, 0.7.2."
+git push origin master
+```
+
+Release.
+
+```
+$ rake release
+
+grape-swagger 0.7.2 built to pkg/grape-swagger-0.7.2.gem.
+Tagged v0.7.2.
+Pushed git commits and tags.
+Pushed grape-swagger 0.7.2 to rubygems.org.
+```
+
+### Prepare for the Next Version
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+Next Release
+============
+
+* Your contribution here.
+```
+
+Comit your changes.
+
+```
+git add CHANGELOG.md
+git commit -m "Preparing for next release."
+git push origin master
+```
+
+### Make an Announcement
+
+Make an announcement on the [ruby-grape@googlegroups.com](mailto:ruby-grape@googlegroups.com) mailing list. The general format is as follows.
+
+```
+Grape-Swagger 0.7.2 has been released.
+
+There were 8 contributors to this release, not counting documentation.
+
+Please note the breaking API change in ...
+
+[copy/paste CHANGELOG here]
+
+```

data/Rakefile

@@ -2,30 +2,10 @@
 
 require 'rubygems'
 require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "grape-swagger"
-  gem.homepage = "http://github.com/tim-vandecasteele/grape-swagger"
-  gem.license = "MIT"
-  gem.summary = %Q{Add swagger compliant documentation to your grape API}
-  gem.description = %Q{A simple way to add proper auto generated documentation - that can be displayed with swagger - to your inline described grape API}
-  gem.email = "tim.vandecasteele@gmail.com"
-  gem.authors = ["Tim Vandecasteele"]
-  # dependencies defined in Gemfile
-end
-Jeweler::RubygemsDotOrgTasks.new
 
+Bundler.setup(:default, :development)
 
+require 'rake'
 
 Bundler::GemHelper.install_tasks
 
@@ -34,4 +14,7 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: [:rubocop, :spec]

data/UPGRADING.md

@@ -0,0 +1,47 @@
+Upgrading Grape-swagger
+=======================
+
+### Upgrading to >= 0.8.0
+
+#### Changes in Configuration
+
+The following options have been added, removed or have been changed in the grape-swagger interface:
+
+* `markdown: true/false` => `markdown: GrapeSwagger::Markdown::KramdownAdapter`
+
+#### Markdown
+
+You can now configure a markdown adapter. This was originally changed because of performance issues with Kramdown and the `markdown` option no longer takes a boolean argument. Built-in adapters include Kramdown and Redcarpet.
+
+##### Kramdown
+
+To configure the markdown with Kramdown, add the kramdown gem to your Gemfile:
+
+`gem 'kramdown'`
+
+Configure grape-swagger as follows:
+
+```ruby
+add_swagger_documentation (
+    markdown: GrapeSwagger::Markdown::KramdownAdapter
+)
+```
+
+#### Redcarpet
+
+To configure markdown with Redcarpet, add the redcarpet and the rouge gem to your Gemfile. Note that Redcarpet does not work with JRuby.
+
+```ruby
+gem 'redcarpet'
+gem 'rouge'
+```
+
+Configure grape-swagger as follows:
+
+```ruby
+add_swagger_documentation (
+    markdown: GrapeSwagger::Markdown::RedcarpetAdapter
+)
+```
+
+See [#142](https://github.com/tim-vandecasteele/grape-swagger/pull/142) and documentation section [Markdown in Notes](https://github.com/tim-vandecasteele/grape-swagger#markdown-in-notes) for more information.

data/grape-swagger.gemspec

@@ -1,90 +1,32 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
-# -*- encoding: utf-8 -*-
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+require 'grape-swagger/version'
 
 Gem::Specification.new do |s|
-  s.name = "grape-swagger"
-  s.version = "0.7.2"
+  s.name        = 'grape-swagger'
+  s.version     = GrapeSwagger::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Tim Vandecasteele']
+  s.email       = ['tim.vandecasteele@gmail.com']
+  s.homepage    = 'https://github.com/tim-vandecasteele/grape-swagger'
+  s.summary     = 'A simple way to add auto generated documentation to your Grape API that can be displayed with Swagger.'
+  s.license     = 'MIT'
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Tim Vandecasteele"]
-  s.date = "2014-02-06"
-  s.description = "A simple way to add proper auto generated documentation - that can be displayed with swagger - to your inline described grape API"
-  s.email = "tim.vandecasteele@gmail.com"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.markdown"
-  ]
-  s.files = [
-    ".document",
-    ".rspec",
-    ".rvmrc",
-    ".travis.yml",
-    "CHANGELOG.markdown",
-    "Gemfile",
-    "Gemfile.lock",
-    "LICENSE.txt",
-    "README.markdown",
-    "Rakefile",
-    "VERSION",
-    "grape-swagger.gemspec",
-    "lib/grape-swagger.rb",
-    "spec/api_models_spec.rb",
-    "spec/default_api_spec.rb",
-    "spec/form_params_spec.rb",
-    "spec/grape-swagger_helper_spec.rb",
-    "spec/grape-swagger_spec.rb",
-    "spec/hide_api_spec.rb",
-    "spec/non_default_api_spec.rb",
-    "spec/simple_mounted_api_spec.rb",
-    "spec/spec_helper.rb",
-    "test/config.ru",
-    "test/nested_api.rb"
-  ]
-  s.homepage = "http://github.com/tim-vandecasteele/grape-swagger"
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.23"
-  s.summary = "Add swagger compliant documentation to your grape API"
+  s.add_runtime_dependency 'grape'
+  s.add_runtime_dependency 'grape-entity'
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'shoulda'
+  s.add_development_dependency 'rdoc'
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'rack-cors'
+  s.add_development_dependency 'rubocop', '0.24.1'
+  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'
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<grape>, [">= 0.2.0"])
-      s.add_runtime_dependency(%q<grape-entity>, [">= 0.3.0"])
-      s.add_runtime_dependency(%q<kramdown>, [">= 1.3.1"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_development_dependency(%q<bundler>, ["> 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_development_dependency(%q<pry>, [">= 0"])
-      s.add_development_dependency(%q<rack-test>, [">= 0"])
-      s.add_development_dependency(%q<rspec>, [">= 0"])
-    else
-      s.add_dependency(%q<grape>, [">= 0.2.0"])
-      s.add_dependency(%q<grape-entity>, [">= 0.3.0"])
-      s.add_dependency(%q<kramdown>, [">= 1.3.1"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_dependency(%q<bundler>, ["> 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_dependency(%q<pry>, [">= 0"])
-      s.add_dependency(%q<rack-test>, [">= 0"])
-      s.add_dependency(%q<rspec>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<grape>, [">= 0.2.0"])
-    s.add_dependency(%q<grape-entity>, [">= 0.3.0"])
-    s.add_dependency(%q<kramdown>, [">= 1.3.1"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
-    s.add_dependency(%q<bundler>, ["> 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-    s.add_dependency(%q<pry>, [">= 0"])
-    s.add_dependency(%q<rack-test>, [">= 0"])
-    s.add_dependency(%q<rspec>, [">= 0"])
-  end
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")
+  s.require_paths = ['lib']
 end
-

data/lib/grape-swagger.rb

@@ -1,38 +1,48 @@
-require 'kramdown'
+require 'grape-swagger/version'
+require 'grape-swagger/errors'
+require 'grape-swagger/markdown'
+require 'grape-swagger/markdown/kramdown_adapter'
+require 'grape-swagger/markdown/redcarpet_adapter'
 
 module Grape
   class API
     class << self
-      attr_reader :combined_routes
+      attr_reader :combined_routes, :combined_namespaces
 
-      def add_swagger_documentation(options={})
+      def add_swagger_documentation(options = {})
         documentation_class = create_documentation_class
 
-        documentation_class.setup({:target_class => self}.merge(options))
+        documentation_class.setup({ target_class: self }.merge(options))
         mount(documentation_class)
 
         @combined_routes = {}
-
         routes.each do |route|
           route_match = route.route_path.split(route.route_prefix).last.match('\/([\w|-]*?)[\.\/\(]')
           next if route_match.nil?
           resource = route_match.captures.first
           next if resource.empty?
           resource.downcase!
-
           @combined_routes[resource] ||= []
-
-          unless @@hide_documentation_path and route.route_path.include?(@@mount_path)
-            @combined_routes[resource] << route
-          end
+          next if @@hide_documentation_path && route.route_path.include?(@@mount_path)
+          @combined_routes[resource] << route
         end
 
+        @combined_namespaces = {}
+        combine_namespaces(self)
       end
 
       private
 
-      def create_documentation_class
+      def combine_namespaces(app)
+        app.endpoints.each do |endpoint|
+          ns = endpoint.settings.stack.last[:namespace]
+          @combined_namespaces[ns.space] = ns if ns
 
+          combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
+        end
+      end
+
+      def create_documentation_class
         Class.new(Grape::API) do
           class << self
             def name
@@ -42,19 +52,20 @@ module Grape
 
           def self.setup(options)
             defaults = {
-              :target_class             => nil,
-              :mount_path               => '/swagger_doc',
-              :base_path                => nil,
-              :api_version              => '0.1',
-              :markdown                 => false,
-              :hide_documentation_path  => false,
-              :hide_format              => false,
-              :format                   => nil,
-              :models                   => [],
-              :info                     => {},
-              :authorizations           => nil,
-              :root_base_path           => true,
-              :include_base_url         => true
+              target_class: nil,
+              mount_path: '/swagger_doc',
+              base_path: nil,
+              api_version: '0.1',
+              markdown: nil,
+              hide_documentation_path: false,
+              hide_format: false,
+              format: nil,
+              models: [],
+              info: {},
+              authorizations: nil,
+              root_base_path: true,
+              api_documentation: { desc: 'Swagger compatible API description' },
+              specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }
             }
 
             options = defaults.merge(options)
@@ -62,14 +73,16 @@ module Grape
             target_class     = options[:target_class]
             @@mount_path     = options[:mount_path]
             @@class_name     = options[:class_name] || options[:mount_path].gsub('/', '')
-            @@markdown       = options[:markdown]
+            @@markdown       = options[:markdown] ? GrapeSwagger::Markdown.new(options[:markdown]) : nil
             @@hide_format    = options[:hide_format]
             api_version      = options[:api_version]
             base_path        = options[:base_path]
             authorizations   = options[:authorizations]
-            include_base_url = options[:include_base_url]
             root_base_path   = options[:root_base_path]
             extra_info       = options[:info]
+            api_doc          = options[:api_documentation].dup
+            specific_api_doc = options[:specific_api_documentation].dup
+            @@models         = options[:models] || []
 
             @@hide_documentation_path = options[:hide_documentation_path]
 
@@ -79,82 +92,109 @@ module Grape
               end
             end
 
-            desc 'Swagger compatible API description'
+            desc api_doc.delete(:desc), params: api_doc.delete(:params)
+            @last_description.merge!(api_doc)
             get @@mount_path do
               header['Access-Control-Allow-Origin']   = '*'
               header['Access-Control-Request-Method'] = '*'
 
-              routes = target_class::combined_routes
+              routes = target_class.combined_routes
+              namespaces = target_class.combined_namespaces
 
               if @@hide_documentation_path
-                routes.reject!{ |route, value| "/#{route}/".index(parse_path(@@mount_path, nil) << '/') == 0 }
+                routes.reject! { |route, _value| "/#{route}/".index(parse_path(@@mount_path, nil) << '/') == 0 }
               end
 
               routes_array = routes.keys.map do |local_route|
                 next if routes[local_route].all?(&:route_hidden)
 
-                url_base    = parse_path(route.route_path.gsub('(.:format)', ''), route.route_version) if include_base_url
                 url_format  = '.{format}' unless @@hide_format
+
+                description = namespaces[local_route] && namespaces[local_route].options[:desc]
+                description ||= "Operations about #{local_route.pluralize}"
+
                 {
-                  :path => "#{url_base}/#{local_route}#{url_format}",
-                  #:description => "..."
+                  path: "/#{local_route}#{url_format}",
+                  description: description
                 }
               end.compact
 
               output = {
                 apiVersion:     api_version,
-                swaggerVersion: "1.2",
+                swaggerVersion: '1.2',
                 produces:       content_types_for(target_class),
-                operations:     [],
                 apis:           routes_array,
                 info:           parse_info(extra_info)
               }
 
-              basePath                = parse_base_path(base_path, request)
-              output[:basePath]       = basePath        if basePath && basePath.size > 0 && root_base_path != false
-              output[:authorizations] = authorizations  if authorizations
+              output[:authorizations] = authorizations unless authorizations.nil? || authorizations.empty?
 
               output
             end
 
-            desc 'Swagger compatible API description for specific API', :params => {
-              "name" => {
-                :desc     => "Resource name of mounted API",
-                :type     => "string",
-                :required => true
+            desc specific_api_doc.delete(:desc), params: {
+              'name' => {
+                desc: 'Resource name of mounted API',
+                type: 'string',
+                required: true
               }
-            }
+            }.merge(specific_api_doc.delete(:params) || {})
+            @last_description.merge!(specific_api_doc)
             get "#{@@mount_path}/:name" do
               header['Access-Control-Allow-Origin']   = '*'
               header['Access-Control-Request-Method'] = '*'
 
               models = []
-              routes = target_class::combined_routes[params[:name]]
+              routes = target_class.combined_routes[params[:name]]
+              error!('Not Found', 404) unless routes
 
               ops = routes.reject(&:route_hidden).group_by do |route|
                 parse_path(route.route_path, api_version)
               end
 
+              error!('Not Found', 404) unless ops.any?
+
               apis = []
 
-              ops.each do |path, routes|
-                operations = routes.map do |route|
+              ops.each do |path, op_routes|
+                operations = op_routes.map do |route|
                   notes       = as_markdown(route.route_notes)
-                  http_codes  = parse_http_codes(route.route_http_codes)
 
-                  models << route.route_entity if route.route_entity
+                  http_codes  = parse_http_codes(route.route_http_codes, models)
+
+                  models << @@models if @@models.present?
+
+                  models << route.route_entity if route.route_entity.present?
+
+                  models = models_with_included_presenters(models.flatten.compact)
 
                   operation = {
-                    :produces   => content_types_for(target_class),
-                    :notes      => notes.to_s,
-                    :summary    => route.route_description || '',
-                    :nickname   => route.route_nickname || (route.route_method + route.route_path.gsub(/[\/:\(\)\.]/,'-')),
-                    :httpMethod => route.route_method,
-                    :parameters => parse_header_params(route.route_headers) +
-                      parse_params(route.route_params, route.route_path, route.route_method)
+                    notes: notes.to_s,
+                    summary: route.route_description || '',
+                    nickname: route.route_nickname || (route.route_method + route.route_path.gsub(/[\/:\(\)\.]/, '-')),
+                    method: route.route_method,
+                    parameters: parse_header_params(route.route_headers) + parse_params(route.route_params, route.route_path, route.route_method),
+                    type: 'void'
                   }
-                  operation.merge!(:type => parse_entity_name(route.route_entity)) if route.route_entity
-                  operation.merge!(:responseMessages => http_codes) unless http_codes.empty?
+                  operation[:authorizations] = route.route_authorizations unless route.route_authorizations.nil? || route.route_authorizations.empty?
+                  if operation[:parameters].any? { | param | param[:type] == 'File' }
+                    operation.merge!(consumes: ['multipart/form-data'])
+                  end
+                  operation.merge!(responseMessages: http_codes) unless http_codes.empty?
+
+                  if route.route_entity
+                    type = parse_entity_name(route.route_entity)
+                    if route.instance_variable_get(:@options)[:is_array]
+                      operation.merge!(
+                        'type' => 'array',
+                        'items' => generate_typeref(type)
+                      )
+                    else
+                      operation.merge!('type' => type)
+                    end
+                  end
+
+                  operation[:nickname] = route.route_nickname if route.route_nickname
                   operation
                 end.compact
                 apis << {
@@ -165,14 +205,16 @@ module Grape
 
               api_description = {
                 apiVersion:     api_version,
-                swaggerVersion: "1.2",
-                resourcePath:   "",
+                swaggerVersion: '1.2',
+                resourcePath:   "/#{params[:name]}",
+                produces:       content_types_for(target_class),
                 apis:           apis
               }
 
-              basePath                   = parse_base_path(base_path, request)
-              api_description[:basePath] = basePath if basePath && basePath.size > 0
-              api_description[:models]   = parse_entity_models(models) unless models.empty?
+              base_path                        = parse_base_path(base_path, request)
+              api_description[:basePath]       = base_path if base_path && base_path.size > 0 && root_base_path != false
+              api_description[:models]         = parse_entity_models(models) unless models.empty?
+              api_description[:authorizations] = authorizations if authorizations
 
               api_description
             end
@@ -181,37 +223,70 @@ module Grape
           helpers do
 
             def as_markdown(description)
-              description && @@markdown ? Kramdown::Document.new(strip_heredoc(description), :input => 'GFM', :enable_coderay => false).to_html : description
+              description && @@markdown ? @@markdown.as_markdown(strip_heredoc(description)) : description
             end
 
             def parse_params(params, path, method)
               params ||= []
-
               params.map do |param, value|
-                value[:type] = 'file' if value.is_a?(Hash) && value[:type] == 'Rack::Multipart::UploadedFile'
-
-                dataType    = value.is_a?(Hash) ? (value[:type] || 'String').to_s : 'String'
-                description = value.is_a?(Hash) ? value[:desc] || value[:description] : ''
-                required    = value.is_a?(Hash) ? !!value[:required] : false
-                defaultValue = value.is_a?(Hash) ? value[:defaultValue] : nil
-                paramType = if path.include?(":#{param}")
-                   'path'
+                value[:type] = 'File' if value.is_a?(Hash) && ['Rack::Multipart::UploadedFile', 'Hash'].include?(value[:type])
+                items = {}
+
+                raw_data_type = value.is_a?(Hash) ? (value[:type] || 'string').to_s : 'string'
+                data_type     = case raw_data_type
+                                when 'Boolean', 'Date', 'Integer', 'String'
+                                  raw_data_type.downcase
+                                when 'BigDecimal'
+                                  'long'
+                                when 'DateTime'
+                                  'dateTime'
+                                when 'Numeric'
+                                  'double'
+                                else
+                                  parse_entity_name(raw_data_type)
+                                end
+                description   = value.is_a?(Hash) ? value[:desc] || value[:description] : ''
+                required      = value.is_a?(Hash) ? !!value[:required] : false
+                default_value = value.is_a?(Hash) ? value[:default] : nil
+                is_array      = value.is_a?(Hash) ? (value[:is_array] || false) : false
+                enum_values   = value.is_a?(Hash) ? value[:values] : nil
+                enum_values   = enum_values.call if enum_values && enum_values.is_a?(Proc)
+
+                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
-                  %w[ POST PUT PATCH ].include?(method) ? 'form' : '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
+                name          = (value.is_a?(Hash) && value[:full_name]) || param
 
                 parsed_params = {
-                  paramType:    paramType,
-                  name:         name,
-                  description:  as_markdown(description),
-                  type:         dataType,
-                  dataType:     dataType,
-                  required:     required
+                  paramType:     param_type,
+                  name:          name,
+                  description:   as_markdown(description),
+                  type:          data_type,
+                  required:      required,
+                  allowMultiple: is_array
                 }
-
-                parsed_params.merge!({defaultValue: defaultValue}) if defaultValue
-
+                parsed_params.merge!(format: 'int32') if data_type == 'integer'
+                parsed_params.merge!(format: 'int64') if data_type == 'long'
+                parsed_params.merge!(items: items) if items.present?
+                parsed_params.merge!(defaultValue: default_value) if default_value
+                parsed_params.merge!(enum: enum_values) if enum_values
                 parsed_params
               end
             end
@@ -222,7 +297,7 @@ module Grape
               if content_types.empty?
                 formats       = [target_class.settings[:format], target_class.settings[:default_format]].compact.uniq
                 formats       = Grape::Formatter::Base.formatters({}).keys if formats.empty?
-                content_types = Grape::ContentTypes::CONTENT_TYPES.select{|content_type, mime_type| formats.include? content_type}.values
+                content_types = Grape::ContentTypes::CONTENT_TYPES.select { |content_type, _mime_type| formats.include? content_type }.values
               end
 
               content_types.uniq
@@ -231,34 +306,33 @@ module Grape
             def parse_info(info)
               {
                 contact:            info[:contact],
-                description:        info[:description],
+                description:        as_markdown(info[:description]),
                 license:            info[:license],
                 licenseUrl:         info[:license_url],
                 termsOfServiceUrl:  info[:terms_of_service_url],
                 title:              info[:title]
-              }.delete_if{|_, value| value.blank?}
+              }.delete_if { |_, value| value.blank? }
             end
 
             def parse_header_params(params)
               params ||= []
 
               params.map do |param, value|
-                dataType    = 'String'
-                description = value.is_a?(Hash) ? value[:description] : ''
-                required    = value.is_a?(Hash) ? !!value[:required] : false
-                defaultValue = value.is_a?(Hash) ? value[:defaultValue] : nil
-                paramType   = "header"
+                data_type     = 'String'
+                description   = value.is_a?(Hash) ? value[:description] : ''
+                required      = value.is_a?(Hash) ? !!value[:required] : false
+                default_value = value.is_a?(Hash) ? value[:default] : nil
+                param_type    = 'header'
 
                 parsed_params = {
-                  paramType:    paramType,
+                  paramType:    param_type,
                   name:         param,
                   description:  as_markdown(description),
-                  type:         dataType,
-                  dataType:     dataType,
+                  type:         data_type,
                   required:     required
                 }
 
-                parsed_params.merge!({defaultValue: defaultValue}) if defaultValue
+                parsed_params.merge!(defaultValue: default_value) if default_value
 
                 parsed_params
               end
@@ -277,46 +351,98 @@ module Grape
               version ? parsed_path.gsub('{version}', version) : parsed_path
             end
 
-            def parse_entity_name(name)
-              entity_parts = name.to_s.split('::')
-              entity_parts.reject! {|p| p == "Entity" || p == "Entities"}
-              entity_parts.join("::")
+            def parse_entity_name(model)
+              if model.respond_to?(:entity_name)
+                model.entity_name
+              else
+                name = model.to_s
+                entity_parts = name.split('::')
+                entity_parts.reject! { |p| p == 'Entity' || p == 'Entities' }
+                entity_parts.join('::')
+              end
             end
 
             def parse_entity_models(models)
               result = {}
-
               models.each do |model|
-                name        = parse_entity_name(model)
-                properties  = {}
+                name       = parse_entity_name(model)
+                properties = {}
+                required   = []
 
                 model.documentation.each do |property_name, property_info|
-                  properties[property_name] = property_info
+                  p = property_info.dup
+
+                  required << property_name.to_s if p.delete(:required)
+
+                  if p.delete(:is_array)
+                    p[:items] = generate_typeref(p[:type])
+                    p[:type] = 'array'
+                  else
+                    p.merge! generate_typeref(p.delete(:type))
+                  end
 
                   # rename Grape Entity's "desc" to "description"
-                  if property_description = property_info.delete(:desc)
-                    property_info[:description] = property_description
+                  property_description = p.delete(:desc)
+                  p[:description] = property_description if property_description
+
+                  # rename Grape's 'values' to 'enum'
+                  select_values = p.delete(:values)
+                  if select_values
+                    select_values = select_values.call if select_values.is_a?(Proc)
+                    p[:enum] = select_values
                   end
+
+                  properties[property_name] = p
+
                 end
 
                 result[name] = {
                   id:         model.instance_variable_get(:@root) || name,
-                  name:       model.instance_variable_get(:@root) || name,
                   properties: properties
                 }
+                result[name].merge!(required: required) unless required.empty?
               end
 
               result
             end
 
-            def parse_http_codes codes
+            def models_with_included_presenters(models)
+              all_models = models
+
+              models.each do |model|
+                # get model references from exposures with a documentation
+                additional_models = model.exposures.map do |_, config|
+                  config[:using] if config.key?(:documentation)
+                end.compact
+
+                all_models += additional_models
+              end
+
+              all_models
+            end
+
+            def is_primitive?(type)
+              %w(integer long float double string byte boolean date dateTime).include? type
+            end
+
+            def generate_typeref(type)
+              if is_primitive? type
+                { 'type' => type }
+              else
+                { '$ref' => type }
+              end
+            end
+
+            def parse_http_codes(codes, models)
               codes ||= {}
-              codes.map do |k, v|
-                {
+              codes.map do |k, v, m|
+                models << m if m
+                http_code_hash = {
                   code: k,
-                  message: v,
-                  #responseModel: ...
+                  message: v
                 }
+                http_code_hash[:responseModel] = parse_entity_name(m) if m
+                http_code_hash
               end
             end