grape-swagger 0.27.1 → 0.27.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d4da1b29c0c251744171e78d2d8e7f9911c8b0d
-  data.tar.gz: 24c02ffce502d8e7379fbde275c9f747f3bc07d3
+  metadata.gz: cd96ed3b622fb9377315f85c54a8bc7a48bca789
+  data.tar.gz: f422e01c1efc38591c61e0b9e547e2935b543d92
 SHA512:
-  metadata.gz: cf0dadce63c9f23539eab02f871cbaeeccc6a39af8ca7b2e588fe3082301eed7e913ab2e77d1cbcfb7b90f56f645bad348fa5248b609677ab5a436df4026f633
-  data.tar.gz: 6b094b917156606be769a220c74a06198b0721e54e2a456b8104baad7c1605ec1e2642d01f308778cb260e4ab7dd7313be8d913b0eef7225d32c7b2fd0f62d09
+  metadata.gz: 6ad5d364859f7eaef34fb16805b5ba7dbbb8c1c79c84d4b76f18d5635b17237cd11cb7a849107d24ffe6eea98c99babd8ff287dcf5c233a877d6f573f35633fc
+  data.tar.gz: 135704aca1becf4c1f25cfcf4c0d1ebe71357fb7d637f151d589ba26cca9c7dad00f945e6948108e632a985abfdb727a322dcb02672ed972b447ca9e5f842f27

data/CHANGELOG.md

@@ -8,7 +8,15 @@
 
 * Your contribution here.
 
-### ###  0.27.1 (April 28, 2017)
+### 0.27.2 (May 11, 2017)
+
+#### Features
+
+* [#608](https://github.com/ruby-grape/grape-swagger/pull/608): Support extensions on the root object - [@thogg4](https://github.com/thogg4).
+* [#596](https://github.com/ruby-grape/grape-swagger/pull/596): Use route_settings for hidden and operations extensions - [@thogg4](https://github.com/thogg4).
+* [#607](https://github.com/ruby-grape/grape-swagger/pull/607): Allow body parameter name to be specified - [@tjwp](https://github.com/tjwp).
+
+### 0.27.1 (April 28, 2017)
 
 #### Features
 

data/README.md

@@ -458,6 +458,13 @@ Or by adding ```hidden: true``` on the verb method of the endpoint, such as `get
 get '/kittens', hidden: true do
 ```
 
+Or by using a route setting:
+
+```ruby
+route_setting :swagger, { hidden: true }
+gem '/kittens' do
+```
+
 Endpoints can be conditionally hidden by providing a callable object such as a lambda which evaluates to the desired
 state:
 
@@ -521,6 +528,20 @@ end
 ```
 
 
+#### Overriding the name of the body parameter
+
+By default, body parameters have a generated name based on the operation. For
+deeply nested resources, this name can get very long. To override the name of
+body parameter add `body_name: 'post_body'` after the description.
+
+```ruby
+namespace 'order' do
+  desc 'Create an order', body_name: 'post_body'
+  post do
+    ...
+  end
+end
+```
 
 #### Defining an endpoint as an array <a name="array" />
 
@@ -885,11 +906,29 @@ end
 #### Extensions <a name="extensions" />
 
 Swagger spec2.0 supports extensions on different levels, for the moment,
-the documentation on `info`, `verb`, `path` and `definition` level would be supported.
+the documentation on the root level object and the `info`, `verb`, `path` and `definition` levels are supported.
 The documented key would be generated from the `x` + `-` + key of the submitted hash,
 for possibilities refer to the [extensions spec](spec/lib/extensions_spec.rb).
 To get an overview *how* the extensions would be defined on grape level, see the following examples:
 
+- root object extension, add a `x` key to the root hash when calling ```add_swagger_documentation```:
+```ruby
+  add_swagger_documentation \
+    x: {
+      some: 'stuff'
+    },
+    info: {
+    }
+```
+this would generate:
+```json
+{
+  "x-some": "stuff",
+  "info":{
+  }
+}
+```
+
 - `info` extension, add a `x` key to the `info` hash when calling ```add_swagger_documentation```:
 ```ruby
   add_swagger_documentation \
@@ -919,6 +958,20 @@ this would generate:
 }
 ```
 
+- `operation` extension, by setting via route settings::
+```ruby
+route_setting :x_operation, { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "get":{
+    "…":"…",
+    "x-some":"stuff"
+  }
+}
+```
+
 - `path` extension, by setting via route settings:
 ```ruby
 route_setting :x_path, { some: 'stuff' }

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

@@ -11,14 +11,23 @@ module GrapeSwagger
           add_extension_to(path[method], extension(description)) if description && extended?(description, :x)
 
           settings = route.settings
+          add_extensions_to_operation(settings, path, route) if settings && extended?(settings, :x_operation)
           add_extensions_to_path(settings, path) if settings && extended?(settings, :x_path)
           add_extensions_to_definition(settings, path, definitions) if settings && extended?(settings, :x_def)
         end
 
+        def add_extensions_to_root(settings, object)
+          add_extension_to(object, extension(settings)) if extended?(settings, :x)
+        end
+
         def add_extensions_to_info(settings, info)
           add_extension_to(info, extension(settings)) if extended?(settings, :x)
         end
 
+        def add_extensions_to_operation(settings, path, route)
+          add_extension_to(path[route.request_method.downcase.to_sym], extension(settings, :x_operation))
+        end
+
         def add_extensions_to_path(settings, path)
           add_extension_to(path, extension(settings, :x_path))
         end

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

@@ -42,9 +42,9 @@ module GrapeSwagger
 
           move_params_to_new(definition, params)
 
-          definition[:description] = route.description if route.respond_to?(:description)
+          definition[:description] = route.description if route.try(:description)
 
-          build_body_parameter(referenced_definition, definition_name)
+          build_body_parameter(referenced_definition, definition_name, route.options)
         end
 
         def move_params_to_new(definition, params)
@@ -150,9 +150,9 @@ module GrapeSwagger
           definition[:required].push(*value)
         end
 
-        def build_body_parameter(reference, name)
+        def build_body_parameter(reference, name, options)
           {}.tap do |x|
-            x[:name] = name
+            x[:name] = options[:body_name] || name
             x[:in] = 'body'
             x[:required] = true
             x[:schema] = { '$ref' => "#/definitions/#{reference}" }

data/lib/grape-swagger/endpoint.rb

@@ -23,17 +23,20 @@ module Grape
     #
     # required keys for SwaggerObject
     def swagger_object(target_class, request, options)
-      {
-        info:           info_object(options[:info].merge(version: options[:doc_version])),
-        swagger:        '2.0',
-        produces:       content_types_for(target_class),
-        authorizations: options[:authorizations],
+      object = {
+        info:                info_object(options[:info].merge(version: options[:doc_version])),
+        swagger:             '2.0',
+        produces:            content_types_for(target_class),
+        authorizations:      options[:authorizations],
         securityDefinitions: options[:security_definitions],
-        security: options[:security],
-        host:           GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
-        basePath:       GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
-        schemes:        options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
-      }.delete_if { |_, value| value.blank? }
+        security:            options[:security],
+        host:                GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
+        basePath:            GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
+        schemes:             options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
+      }
+
+      GrapeSwagger::DocMethods::Extensions.add_extensions_to_root(options, object)
+      object.delete_if { |_, value| value.blank? }
     end
 
     # building info object
@@ -338,7 +341,8 @@ module Grape
     end
 
     def hidden?(route, options)
-      route_hidden = route.options[:hidden]
+      route_hidden = route.settings.try(:[], :swagger).try(:[], :hidden)
+      route_hidden = route.options[:hidden] if route.options.key?(:hidden)
       return route_hidden unless route_hidden.is_a?(Proc)
       options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call
     end

data/lib/grape-swagger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeSwagger
-  VERSION = '0.27.1'
+  VERSION = '0.27.2'
 end

data/spec/lib/move_params_spec.rb

@@ -94,18 +94,13 @@ describe GrapeSwagger::DocMethods::MoveParams do
 
   describe 'parent_definition_of_params' do
     let(:path) { '/in_body' }
+    let(:route_options) { { requirements: {} } }
     describe 'POST' do
       let(:params) { paths[path][:post][:parameters] }
-      let(:options)  do
-        {
-          method: 'POST'
-        }
-      end
-      let(:env) { Rack::MockRequest.env_for(path, options) }
-      let(:request) { Grape::Request.new(env) }
+      let(:route) { Grape::Router::Route.new('POST', path.dup, route_options) }
 
       specify do
-        subject.to_definition(path, params, request, definitions)
+        subject.to_definition(path, params, route, definitions)
         expect(params).to eql(
           [
             { name: 'InBody', in: 'body', required: true, schema: { '$ref' => '#/definitions/postInBody' } }
@@ -118,16 +113,10 @@ describe GrapeSwagger::DocMethods::MoveParams do
 
     describe 'POST' do
       let(:params) { paths['/in_body/{key}'][:put][:parameters] }
-      let(:options)  do
-        {
-          method: 'PUT'
-        }
-      end
-      let(:env) { Rack::MockRequest.env_for(path, options) }
-      let(:request) { Grape::Request.new(env) }
+      let(:route) { Grape::Router::Route.new('PUT', path.dup, route_options) }
 
       specify do
-        subject.to_definition(path, params, request, definitions)
+        subject.to_definition(path, params, route, definitions)
         expect(params).to eql(
           [
             { in: 'path', name: 'key', description: nil, type: 'integer', format: 'int32', required: true },
@@ -214,9 +203,20 @@ describe GrapeSwagger::DocMethods::MoveParams do
           { name: name, in: 'body', required: true, schema: { '$ref' => "#/definitions/#{reference}" } }
         end
         specify do
-          parameter = subject.send(:build_body_parameter, reference, name)
+          parameter = subject.send(:build_body_parameter, reference, name, {})
           expect(parameter).to eql expected_param
         end
+
+        describe 'body_name option specified' do
+          let(:route_options) { { body_name: 'body' } }
+          let(:expected_param) do
+            { name: route_options[:body_name], in: 'body', required: true, schema: { '$ref' => "#/definitions/#{reference}" } }
+          end
+          specify do
+            parameter = subject.send(:build_body_parameter, reference, name, route_options)
+            expect(parameter).to eql expected_param
+          end
+        end
       end
     end
 

data/spec/swagger_v2/api_swagger_v2_extensions_spec.rb

@@ -19,10 +19,11 @@ describe 'extensions' do
           { 'declared_params' => declared(params) }
         end
 
+        route_setting :x_operation, some: 'stuff'
+
         desc 'This returns something with extension on verb level',
              params: Entities::UseResponse.documentation,
-             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }],
-             x: { some: 'stuff' }
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
         params do
           requires :id, type: Integer
         end
@@ -57,7 +58,7 @@ describe 'extensions' do
           { 'declared_params' => declared(params) }
         end
 
-        add_swagger_documentation
+        add_swagger_documentation(x: { some: 'stuff' })
       end
     end
   end
@@ -66,6 +67,18 @@ describe 'extensions' do
     TheApi::ExtensionsApi
   end
 
+  describe 'extension on root level' do
+    subject do
+      get '/swagger_doc/path_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to include 'x-some'
+      expect(subject['x-some']).to eql 'stuff'
+    end
+  end
+
   describe 'extension on path level' do
     subject do
       get '/swagger_doc/path_extension'

data/spec/swagger_v2/guarded_endpoint_spec.rb

@@ -56,7 +56,8 @@ describe 'a guarded api endpoint' do
     class GuardedMountedApi < Grape::API
       resource_owner_valid = proc { |token_owner = nil| token_owner.nil? }
 
-      desc 'Show endpoint if authenticated', hidden: resource_owner_valid
+      desc 'Show endpoint if authenticated'
+      route_setting :swagger, hidden: resource_owner_valid
       get '/auth' do
         { foo: 'bar' }
       end

data/spec/swagger_v2/hide_api_spec.rb

@@ -15,6 +15,12 @@ describe 'a hide mounted api' do
         { foo: 'bar' }
       end
 
+      desc 'Hide this endpoint using route setting'
+      route_setting :swagger, hidden: true
+      get '/hide_as_well' do
+        { foo: 'bar' }
+      end
+
       desc 'Lazily show endpoint', hidden: -> { false }
       get '/lazy' do
         { foo: 'bar' }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.27.2
 platform: ruby
 authors:
 - Tim Vandecasteele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-28 00:00:00.000000000 Z
+date: 2017-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -178,7 +178,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: Add auto generated documentation to your Grape API that can be displayed