grape-swagger 0.20.3 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d7b5486e6ee350258521fef6c57ee68169423f0
-  data.tar.gz: 105ff9de1347190740ec19228cc5839246758288
+  metadata.gz: 21b83f7c1596856df6020d2a6191b69a2a9502af
+  data.tar.gz: d3f9532f1a8d5430baa061237d28b8c5fa8fced5
 SHA512:
-  metadata.gz: c22549eeab271d9c11100edb328f91707695632ed36ee4ae201e2e716d1526b9285d068035e356dbaea61098d7d5b6f4c11297af27be3b072c20e7a28ade9ebb
-  data.tar.gz: d2256e0601621560fb665543731632c2177a16a8b0e0b03c1d5bc356cd5f198b779fd81ae2ffc9fac2ad3445ddc114c76b000d88c14c4c850560cb5ef0c505e3
+  metadata.gz: a48aa84a04dcb5b0a6c12fb142e0fefbb92a42f8c363a9a0b34cf3931ea57a60996f2991b5f00e0d5b1154dd4f85b655d16f634101c6913e2cdbd0867ba7d735
+  data.tar.gz: 705b3490be3a33bf84ec5bd56df3d7ea9b698b0b2a79eef822facebb22554933fa1ff2a00e462e36f4df8c8af30d0c06f0c11eae9c4fe8c131eecf22e5fb05eb

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2016-05-06 15:08:19 -0400 using RuboCop version 0.39.0.
+# on 2016-05-11 23:53:37 +0300 using RuboCop version 0.40.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
@@ -23,31 +23,31 @@ Lint/UselessAssignment:
 
 # Offense count: 27
 Metrics/AbcSize:
-  Max: 68
+  Max: 56
 
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 234
+  Max: 206
 
-# Offense count: 11
+# Offense count: 10
 Metrics/CyclomaticComplexity:
   Max: 16
 
-# Offense count: 624
+# Offense count: 719
 # Configuration parameters: AllowHeredoc, AllowURI, URISchemes.
 # URISchemes: http, https
 Metrics/LineLength:
-  Max: 487
+  Max: 454
 
-# Offense count: 33
+# Offense count: 31
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
   Max: 101
 
-# Offense count: 7
+# Offense count: 6
 Metrics/PerceivedComplexity:
-  Max: 19
+  Max: 17
 
 # Offense count: 4
 Style/ClassVars:
@@ -55,7 +55,7 @@ Style/ClassVars:
     - 'example/api/endpoints.rb'
     - 'lib/grape-swagger/doc_methods.rb'
 
-# Offense count: 24
+# Offense count: 27
 Style/Documentation:
   Enabled: false
 

data/.travis.yml

@@ -4,6 +4,10 @@ sudo: false
 
 matrix:
   include:
+    - rvm: 2.3.1
+      env: MODEL_PARSER=grape-swagger-entity
+    - rvm: 2.3.1
+      env: MODEL_PARSER=grape-swagger-representable
     - rvm: 2.3.1
       env: GRAPE_VERSION=0.12.0
     - rvm: 2.3.1
@@ -17,14 +21,15 @@ matrix:
     - rvm: 2.3.1
       env: GRAPE_VERSION=HEAD
     - rvm: 2.3.0
-    - rvm: 2.2.5
+    - rvm: 2.2
     - rvm: 2.1
+    - rvm: ruby-head
     - rvm: rbx-2
+    - rvm: jruby-9.0.5.0
     - rvm: jruby-19mode
-    - rvm: ruby-head
     - rvm: jruby-head
   allow_failures:
+    - rvm: ruby-head
     - rvm: rbx-2
     - rvm: jruby-19mode
-    - rvm: ruby-head
     - rvm: jruby-head

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+### Next
+
+#### Features
+
+* Your contribution here.
+
+#### Fixes
+
+* Your contribution here.
+
+### 0.21.0 (June 1, 2016)
+
+#### Features
+
+* [#413](https://github.com/ruby-grape/grape-swagger/pull/413): Move all model parsing logic to separate gems `grape-swagger-entity` and added representable parser `grape-swagger` - [@Bugagazavr](https://github.com/Bugagazavr).
+* [#434](https://github.com/ruby-grape/grape-swagger/pull/434): Add summary to the operation object generator to be more compliant with [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) - [@aschuster3](https://github.com/aschuster3).
+* [#441](https://github.com/ruby-grape/grape-swagger/pull/441): Accepting `String`, `lambda` and `proc` for `host` and `base_path` - [@LeFnord](https://github.com/LeFnord).
+* Your contribution here.
+
+#### Fixes
+
+* [#416](https://github.com/ruby-grape/grape-swagger/pull/416): Support recursive models - [@lest](https://github.com/lest).
+* [#419](https://github.com/ruby-grape/grape-swagger/pull/419): Replaced github ref to rubygems for external gems - [@Bugagazavr](https://github.com/Bugagazavr).
+* [#420](https://github.com/ruby-grape/grape-swagger/pull/420): Raise SwaggerSpec exception if swagger spec isn't satisfied, when no parser for model is registered or response model is empty - [@Bugagazavr](https://github.com/Bugagazavr).
+* [#438](https://github.com/ruby-grape/grape-swagger/pull/438): Route version was missing in :options passed to PathString, so Endpoint.path_and_definitions_objects wasn't returning a versioned path when required - [@texpert](https://github.com/texpert).
+* Your contribution here.
+
 ### 0.20.3 (May 9, 2016)
 
 #### Features

data/Gemfile

@@ -8,3 +8,5 @@ when 'HEAD'
 else
   gem 'grape', version
 end
+
+gem ENV['MODEL_PARSER'] if ENV.key?('MODEL_PARSER')

data/README.md

@@ -11,6 +11,7 @@
 * [Swagger-Spec](#swagger-spec)
 * [Installation](#install)
 * [Usage](#usage)
+* [Model Parsers](#model_parsers)
 * [Configure](#configure)
 * [Routes Configuration](#routes)
 * [Markdown](#md_usage)
@@ -27,12 +28,13 @@ The grape-swagger gem provides an autogenerated documentation for your [Grape](h
 
 These screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.
 
-
 <a name="related" />
 ## Related Projects
 
 * [Grape](https://github.com/ruby-grape/grape)
-* [Grape Entity](https://github.com/ruby-grape/grape-entity)
+* [Grape Swagger Entity](https://github.com/ruby-grape/grape-swagger-entity)
+  * [Grape Entity](https://github.com/ruby-grape/grape-entity)
+* [Grape Swagger Representable](https://github.com/ruby-grape/grape-swagger-representable)
 * [Swagger UI](https://github.com/wordnik/swagger-ui)
 
 
@@ -41,18 +43,20 @@ These screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) s
 
 The following versions of grape, grape-entity and grape-swagger can currently be used together.
 
-grape-swagger | swagger spec | grape                   | grape-entity
---------------|--------------|-------------------------|-------------
-0.10.5        |     1.2      | >= 0.10.0 ... <= 0.14.0 |  < 0.5.0
-0.11.0        |     1.2      |               >= 0.16.2 |  < 0.5.0
-0.20.1        |     2.0      | >= 0.12.0 ... <= 0.14.0 | <= 0.5.1
-0.20.3        |     2.0      | >= 0.12.0 ... ~> 0.16.2 | ~> 0.5.1
+grape-swagger | swagger spec | grape                   | grape-entity | representable |
+--------------|--------------|-------------------------|--------------|---------------|
+0.10.5        |     1.2      | >= 0.10.0 ... <= 0.14.0 |  < 0.5.0     | n/a           |
+0.11.0        |     1.2      |               >= 0.16.2 |  < 0.5.0     | n/a           |
+0.20.1        |     2.0      | >= 0.12.0 ... <= 0.14.0 | <= 0.5.1     | n/a           |
+0.20.3        |     2.0      | >= 0.12.0 ... ~> 0.16.2 | ~> 0.5.1     | n/a           |
+0.21.0 (next) |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
 
 <a name="swagger-spec" />
 ## Swagger-Spec
 
-Grape-swagger generates documentation per [Swagger Spec 2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md).
+Grape-swagger generates documentation per [Swagger / OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).
 
+<!-- validating: http://bigstickcarpet.com/swagger-parser/www/index.html -->
 
 <a name="install" />
 ## Installation
@@ -71,7 +75,7 @@ Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 <a name="usage" />
 ## Usage
 
-Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc'. See [example/api.rb](example/api.rb) for a simple demo.
+Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc'. See [example/config.ru](example/config.ru) for a simple demo.
 
 
 ```ruby
@@ -91,6 +95,68 @@ end
 To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc).
 
 
+<a name="model_parsers" />
+## Model Parsers
+
+Since 0.21.0, `Grape::Entity` is not a part of grape-swagger, you need to add `grape-swagger-entity` manually to your Gemfile.
+Also added support for [representable](https://github.com/apotonick/representable) via `grape-swagger-representable`.
+
+```ruby
+# For Grape::Entity ( https://github.com/ruby-grape/grape-entity )
+gem 'grape-swagger-entity'
+# For representable ( https://github.com/apotonick/representable )
+gem 'grape-swagger-representable'
+```
+
+If you are not using Rails, make sure to load the parser inside your application initialization logic, e.g., via `require 'grape-swagger/entity'` or `require 'grape-swagger/representable`.
+
+### Custom Model Parsers
+
+You can create your own model parser, for example for [roar](https://github.com/apotonick/roar).
+
+```rb
+module GrapeSwagger
+  module Roar
+    class Parser
+      attr_reader :model
+      attr_reader :endpoint
+
+      def initialize(model, endpoint)
+        @model = model
+        @endpoint = endpoint
+      end
+
+      def call
+        # Parse your model and return hash with model schema for swagger
+      end
+    end
+  end
+end
+```
+
+Then you should register your custom parser.
+
+```rb
+GrapeSwagger.model_parsers.register(GrapeSwagger::Roar::Parser, Roar::Decorator)
+```
+
+To control model parsers sequence, you can insert your parser before or after another parser.
+
+#### insert_before
+
+```rb
+GrapeSwagger.model_parsers.insert_before(GrapeSwagger::Representable::Parser, GrapeSwagger::Roar::Parser, Roar::Decorator)
+```
+
+#### insert_after
+
+```rb
+GrapeSwagger.model_parsers.insert_after(GrapeSwagger::Roar::Parser, GrapeSwagger::Representable::Parser, Representable::Decorator)
+```
+
+As we know, `Roar::Decorator` uses as superclass `Representable::Decorator`, this allow to avoid problem when Roar objects will be processed by `GrapeSwagger::Representable::Parser`, instead `GrapeSwagger::Roar::Parser`.
+
+
 ### CORS
 
 If you use the online demo, make sure your API supports foreign requests by enabling CORS in Grape, otherwise you'll see the API description, but requests on the API won't return. Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.
@@ -135,7 +201,12 @@ You can pass a hash with optional configuration settings to ```add_swagger_docum
 *not all configuration options supported yet*, but is WIP
 
 
-`host` and `base_path` are also accepting a `proc` to evaluate.
+The `host` and `base_path` options also accept a `proc` or `lambda` to evaluate, which is passed a [request](http://www.rubydoc.info/github/rack/rack/Rack/Request) object:
+
+```ruby
+add_swagger_documentation \
+  base_path: proc { |request| request.host =~ /^example/ ? '/api-example' : '/api' }
+```
 
 <a name="host" />
 #### host:
@@ -153,6 +224,8 @@ add_swagger_documentation \
    base_path: '/super/api'
 ```
 
+`host` and `base_path` are also accepting a `proc` or `lambda`
+
 <a name="mount_path" />
 #### mount_path:
 The path where the API documentation is loaded, default is: `/swagger_doc`.
@@ -381,6 +454,32 @@ end
 ```
 
 
+#### Overriding the route summary
+
+By default, the route summary is filled with the value supplied to `desc`.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary'
+  get :order_id do
+    ...
+  end
+end
+```
+
+To override the summary, add `summary: '[string]'` after the description.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary',
+    summary: 'Now this is your summary!'
+  get :order_id do
+    ...
+  end
+end
+```
+
+
 #### Expose nested namespace as standalone route
 
 Use the `nested: false` property in the `swagger` option to make nested namespaces appear as standalone resources.
@@ -441,7 +540,7 @@ Grape allows for an additional documentation hash to be passed to a parameter.
 ```ruby
 params do
   requires :id, type: Integer, desc: 'Coffee ID'
-  requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { example: 72 }
+  requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { default: 72 }
 end
 ```
 

data/UPGRADING.md

@@ -1,6 +1,15 @@
 Upgrading Grape-swagger
 =======================
 
+### Upgrading to >= 0.21.0
+
+With grape >= 0.21.0, `grape-entity` support moved to separate gem `grape-swagger-entity`, if you use grape entity, update your Gemfile:
+
+```ruby
+gem 'grape-swagger'
+gem 'grape-swagger-entity'
+```
+
 ### Upgrading to >= 0.10.2
 
 With grape >= 0.12.0, support for `notes` is replaced by passing a block `detail` option specified. For future compatibility, update your code:

data/grape-swagger.gemspec

@@ -12,8 +12,6 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
 
   s.add_runtime_dependency 'grape', '>= 0.12.0'
-  s.add_runtime_dependency 'grape-entity'
-  s.add_runtime_dependency 'awesome_print'
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'shoulda'
@@ -22,7 +20,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'
+  s.add_development_dependency 'rubocop', '0.40.0'
   s.add_development_dependency 'kramdown'
   s.add_development_dependency 'redcarpet' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
   s.add_development_dependency 'rouge' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')

data/lib/grape-swagger.rb

@@ -7,11 +7,18 @@ require 'grape-swagger/endpoint'
 require 'grape-swagger/errors'
 
 require 'grape-swagger/doc_methods'
+require 'grape-swagger/model_parsers'
 
 require 'grape-swagger/markdown/kramdown_adapter'
 require 'grape-swagger/markdown/redcarpet_adapter'
 
-require 'awesome_print'
+module GrapeSwagger
+  class << self
+    def model_parsers
+      @model_parsers ||= GrapeSwagger::ModelParsers.new
+    end
+  end
+end
 
 module Grape
   class API

data/lib/grape-swagger/doc_methods/optional_object.rb

@@ -4,11 +4,23 @@ module GrapeSwagger
       class << self
         def build(key, options, request = nil)
           if options[key]
-            options[key].is_a?(Proc) ? options[key].call : options[key]
+            return evaluate(key, options, request) if options[key].is_a?(Proc)
+            options[key]
           else
-            request
+            request.send(default_values[key])
           end
         end
+
+        def evaluate(key, options, request)
+          options[key].arity == 0 ? options[key].call : options[key].call(request)
+        end
+
+        def default_values
+          {
+            host: 'host_with_port',
+            base_path: 'script_name'
+          }
+        end
       end
     end
   end

data/lib/grape-swagger/doc_methods/parse_params.rb

@@ -79,12 +79,11 @@ module GrapeSwagger
 
         def param_type(value_type)
           param_type = value_type[:param_type] || value_type[:in]
-          case
-          when value_type[:path].include?("{#{value_type[:param_name]}}")
+          if value_type[:path].include?("{#{value_type[:param_name]}}")
             'path'
-          when param_type
+          elsif param_type
             param_type
-          when %w(POST PUT PATCH).include?(value_type[:method])
+          elsif %w(POST PUT PATCH).include?(value_type[:method])
             GrapeSwagger::DocMethods::DataType.request_primitive?(value_type[:data_type]) ? 'formData' : 'body'
           else
             'query'

data/lib/grape-swagger/doc_methods/path_string.rb

@@ -2,7 +2,8 @@ module GrapeSwagger
   module DocMethods
     class PathString
       class << self
-        def build(path, options = {})
+        def build(route, options = {})
+          path = route.path
           # always removing format
           path.sub!(/\(\.\w+?\)$/, '')
           path.sub!('(.:format)', '')
@@ -13,8 +14,8 @@ module GrapeSwagger
           # set item from path, this could be used for the definitions object
           item = path.gsub(%r{/{(.+?)}}, '').split('/').last.singularize.underscore.camelize || 'Item'
 
-          if options[:version] && options[:add_version]
-            path.sub!('{version}', options[:version].to_s)
+          if route.version && options[:add_version]
+            path.sub!('{version}', route.version.to_s)
           else
             path.sub!('/{version}', '')
           end