grape-swagger 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1c9531be292e7a5a8d3ee086291e248f42f13457
-  data.tar.gz: 8f7cea40f42d1bb5a474f3468000c837eb540699
+  metadata.gz: 99ac4d378547c6998e6c712a83eb82d8277786fb
+  data.tar.gz: 9d18548301ad46bd474671a770c5e528ee7a4f3c
 SHA512:
-  metadata.gz: 133c28324c1637b9117e06e33e4585df7b3c072dba7432784550b1c309b24b1635abd18f97a06ce43b9c9650176a7df7bccb0a4d7ddb4cc80d61ac7ddbd067a1
-  data.tar.gz: 238698df89fbb172922f2224652eddff2fc26d89c593fb90f787bab4293def4d32bcdfd929200c7ef1770b6c33a486feb7435763bae9eb8708e83992c927cd2f
+  metadata.gz: b609366f8b1e964dbffbc0a65593bca55d050ac46cac23896627fd0b2b49f9a2b4fc368022e20d3e2866d458322d083a13f1bc44d7cc36c4bff323d7082497ed
+  data.tar.gz: 6c6e93549bf4b7eebc659155dcb21ce5d999ef811ea1f8dbceb7c6104b35c3765d0ea6ef16fb706303f9dcd86c99811862fd939af471cbb1a5ff730c9c07aa50

data/.rubocop_todo.yml

@@ -28,7 +28,7 @@ Metrics/AbcSize:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 226
+  Max: 240
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:

data/CHANGELOG.md

@@ -8,12 +8,30 @@
 
 * Your contribution here.
 
+### 0.24.0 (September 23, 2016)
+
+#### Features
+
+* [#504](https://github.com/ruby-grape/grape-swagger/pull/504): Added support for set the 'collectionFormat' of arrays - [@rczjns](https://github.com/rczjns).
+* [#502](https://github.com/ruby-grape/grape-swagger/pull/502): Adds specs for rake tasks - [@LeFnord](https://github.com/LeFnord).
+* [#501](https://github.com/ruby-grape/grape-swagger/pull/501): Adds getting of a specified resource for Rake Tasks - [@LeFnord](https://github.com/LeFnord).
+* [#500](https://github.com/ruby-grape/grape-swagger/pull/500): Adds Rake tasks to get and validate OAPI/Swagger documentation - [@LeFnord](https://github.com/LeFnord).
+* [#493](https://github.com/ruby-grape/grape-swagger/pull/493): Swagger UI endpoint authorization. - [@texpert](https://github.com/texpert).
+* [#492](https://github.com/ruby-grape/grape/pull/492): Define security requirements on endpoint methods - [@tomregelink](https://github.com/tomregelink).
+* [#497](https://github.com/ruby-grape/grape-swagger/pull/497): Use ruby-grape-danger in Dangerfile - [@dblock](https://github.com/dblock).
+
+#### Fixes
+
+* [#503](https://github.com/ruby-grape/grape-swagger/pull/503): Corrects exposing of inline definitions - [@LeFnord](https://github.com/LeFnord).
+* [#494](https://github.com/ruby-grape/grape-swagger/pull/494): Header parametes are now included in documentation when body parameters have been defined - [@anakinj](https://github.com/anakinj).
+* [#505](https://github.com/ruby-grape/grape-swagger/pull/505): Combines namespaces with their mounted paths to allow APIs with specified mount_paths - [@KevinLiddle](https://github.com/KevinLiddle).
+
 ### 0.23.0 (August 5, 2016)
 
 #### Features
 
-* [#491](https://github.com/ruby-grape/grape/pull/491): Add `ignore_defaults` option - [@pezholio](https://github.com/pezholio).
-* [#486](https://github.com/ruby-grape/grape/pull/486): Use an automated PR linter, [danger.systems](http://danger.systems) - [@dblock](https://github.com/dblock).
+* [#491](https://github.com/ruby-grape/grape-swagger/pull/491): Add `ignore_defaults` option - [@pezholio](https://github.com/pezholio).
+* [#486](https://github.com/ruby-grape/grape-swagger/pull/486): Use an automated PR linter, [danger.systems](http://danger.systems) - [@dblock](https://github.com/dblock).
 
 #### Fixes
 

data/Dangerfile

@@ -1 +1 @@
-# inherits from https://github.com/ruby-grape/danger
+danger.import_dangerfile(gem: 'ruby-grape-danger')

data/Gemfile

@@ -16,4 +16,8 @@ if RUBY_VERSION < '2.2.2'
   gem 'activesupport', '<5.0.0'
 end
 
-gem 'danger', '~> 2.1', require: false
+group :test do
+  gem 'ruby-grape-danger', '~> 0.1.0', require: false
+  gem 'grape-entity'
+  gem 'grape-swagger-entity'
+end

data/README.md

@@ -14,10 +14,12 @@
 * [Model Parsers](#model_parsers)
 * [Configure](#configure)
 * [Routes Configuration](#routes)
+* [Securing the Swagger UI](#oauth)
 * [Markdown](#md_usage)
 * [Response documentation](#response)
 * [Extensions](#extensions)
 * [Example](#example)
+* [Rake Tasks](#rake)
 
 <a name="what" />
 ## What is grape-swagger?
@@ -50,7 +52,7 @@ grape-swagger | swagger spec | grape                   | grape-entity | represen
 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        |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
-0.21.1 (next) |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
+0.23.0        |     2.0      | >= 0.12.0 ... <= 0.17.0 | <= 0.5.1     | >= 2.4.1      |
 
 <a name="swagger-spec" />
 ## Swagger-Spec
@@ -192,6 +194,9 @@ end
 * [add_version](#add_version)
 * [doc_version](#doc_version)
 * [markdown](#markdown)
+* [endpoint_auth_wrapper](#endpoint_auth_wrapper)
+* [swagger_endpoint_guard](#swagger_endpoint_guard)
+* [oauth_token](#oauth_token)
 * [security_definitions](#security_definitions)
 * [models](#models)
 * [hide_documentation_path](#hide_documentation_path)
@@ -273,6 +278,33 @@ add_swagger_documentation \
   markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
 ```
 
+<a name="endpoint_auth_wrapper" />
+#### endpoint_auth_wrapper:
+Specify the middleware to use for securing endpoints.
+
+```ruby
+add_swagger_documentation \
+   endpoint_auth_wrapper: WineBouncer::OAuth2
+```
+
+<a name="swagger_endpoint_guard" />
+#### swagger_endpoint_guard:
+Specify the method and auth scopes, used by the middleware for securing endpoints.
+
+```ruby
+add_swagger_documentation \
+   swagger_endpoint_guard: 'oauth2 false'
+```
+
+<a name="oauth_token" />
+#### oauth_token:
+Specify the method to get the oauth_token, provided by the middleware.
+
+```ruby
+add_swagger_documentation \
+   oauth_token: 'doorkeeper_access_token'
+```
+
 <a name="security_definitions" />
 #### security_definitions:
 Specify the [Security Definitions Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object)
@@ -518,6 +550,39 @@ end
 }
 ```
 
+#### Collection format of arrays
+
+You can set the collection format of an array, using the documentation hash.
+
+Collection format determines the format of the array if type array is used. Possible values are:
+*  csv - comma separated values foo,bar.
+*  ssv - space separated values foo bar.
+*  tsv - tab separated values foo\tbar.
+*  pipes - pipe separated values foo|bar.
+*  multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData".
+
+```ruby
+params do
+  requires :statuses, type: Array[String], documentation: { collectionFormat: 'multi' }
+end
+post :act do
+  ...
+end
+```
+
+```json
+{
+  "in": "formData",
+  "name": "statuses",
+  "type": "array",
+  "items": {
+      "type": "string"
+  },
+  "collectionFormat": "multi",
+  "required": true
+}
+```
+
 #### Multi types
 
 By default when you set multi types, the first type is selected as swagger type
@@ -765,9 +830,78 @@ module API
 end
 ```
 
+<a name="oauth" />
+## Securing the Swagger UI
+
+
+The Swagger UI on Grape could be secured from unauthorized access using any middleware, which provides certain methods:
+
+- a *before* method to be run in the Grape controller for authorization purpose;
+- some guard method, which could receive as argument a string or an array of authorization scopes;
+- a method which processes and returns the access token received in the HTTP request headers (usually in the 'HTTP_AUTHORIZATION' header).
+
+Below are some examples of securing the Swagger UI on Grape installed along with Ruby on Rails:
+
+- The WineBouncer and Doorkeeper gems are used in the examples;
+- 'rails' and 'wine_bouncer' gems should be required prior to 'grape-swagger' in boot.rb;
+- This works with a fresh PR to WineBouncer which is yet unmerged - [WineBouncer PR](https://github.com/antek-drzewiecki/wine_bouncer/pull/64).
+
+This is how to configure the grape_swagger documentation:
+
+```ruby
+  add_swagger_documentation base_path: '/',
+                            title: 'My API',
+                            doc_version: '0.0.1',
+                            hide_documentation_path: true,
+                            hide_format: true,
+                            endpoint_auth_wrapper: WineBouncer::OAuth2, # This is the middleware for securing the Swagger UI
+                            swagger_endpoint_guard: 'oauth2 false',     # this is the guard method and scope
+                            oauth_token: 'doorkeeper_access_token'      # This is the method returning the access_token
+```
+
+The guard method should inject the Security Requirement Object into the endpoint's route settings (see Grape::DSL::Settings.route_setting method).
+
+The 'oauth2 false' added to swagger_documentation is making the main Swagger endpoint protected with OAuth, i.e. it
+is retreiving the access_token from the HTTP request, but the 'false' scope is for skipping authorization and showing
+ the UI for everyone. If the scope would be set to something else, like 'oauth2 admin', for example, than the UI
+ wouldn't be displayed at all to unauthorized users.  
+
+Further on, the guard could be used, where necessary, for endpoint access protection. Put it prior to the endpoint's method:
+
+```ruby
+  resource :users do
+    oauth2 'read, write'
+    get do
+      render_users
+    end
+
+    oauth2 'admin'
+    post do
+      User.create!...
+    end
+  end
+```
+
+And, finally, if you want to not only restrict the access, but to completely hide the endpoint from unauthorized
+users, you could pass a lambda to the :hidden key of a endpoint's description:
+
+```ruby
+  not_admins = lambda { |token=nil| token.nil? || !User.find(token.resource_owner_id).admin? }
+
+  resource :users do
+    desc 'Create user', hidden: not_admins
+    oauth2 'admin'
+    post do
+      User.create!...
+    end
+  end
+```
+
+The lambda is checking whether the user is authenticated (if not, the token is nil by default), and has the admin
+role - only admins can see this endpoint.
 
 <a name="md_usage" />
-### Markdown in Detail
+## Markdown in Detail
 
 The grape-swagger gem allows you to add an explanation in markdown in the detail field. Which would result in proper formatted markdown in Swagger UI.
 Grape-swagger uses adapters for several markdown formatters. It includes adapters for [kramdown](http://kramdown.rubyforge.org) (kramdown [syntax](http://kramdown.rubyforge.org/syntax.html)) and [redcarpet](https://github.com/vmg/redcarpet).
@@ -961,19 +1095,20 @@ route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }
 ```
 
 <a="example" />
-# Example
+## Example
 
 Go into example directory and run it: `$ bundle exec rackup`
 go to: `http://localhost:9292/swagger_doc` to get it
 
 For request examples load the [postman file]()
-## Grouping the API list using Namespace
+
+#### Grouping the API list using Namespace
 
 Use namespace for grouping APIs
 
 ![grape-swagger-v2-new-corrected](https://cloud.githubusercontent.com/assets/1027590/13516020/979cfefa-e1f9-11e5-9624-f4a6b17a3c8a.png)
 
-# Example
+#### Example Code
 
 ```ruby
 class NamespaceApi < Grape::API
@@ -1005,6 +1140,38 @@ end
 
 ```
 
+
+<a name="rake" />
+## Rake Tasks
+
+Add these lines to your Rakefile, and initialize the Task class with your Api class – be sure your Api class is available.
+
+```ruby
+require 'grape-swagger/rake/oapi_tasks'
+GrapeSwagger::Rake::OapiTasks.new(::Api::Base)
+```
+
+#### OpenApi/Swagger Documentation
+
+```
+rake oapi:fetch
+params:
+- store={ true | file_name } – save as JSON (optional)
+- resource=resource_name     – get only for this one (optional)
+```
+
+#### OpenApi/Swagger Validation
+
+**requires**: `npm` and `swagger-cli` to be installed
+
+
+```
+rake oapi:validate
+params:
+- resource=resource_name – get only for this one (optional)
+```
+
+
 ## Contributing to grape-swagger
 
 See [CONTRIBUTING](CONTRIBUTING.md).

data/lib/grape-swagger.rb

@@ -18,6 +18,7 @@ module GrapeSwagger
       @model_parsers ||= GrapeSwagger::ModelParsers.new
     end
   end
+  autoload :Rake, 'grape-swagger/rake/oapi_tasks'
 end
 
 module Grape
@@ -31,6 +32,11 @@ module Grape
         version_for(options)
         options = { target_class: self }.merge(options)
         @target_class = options[:target_class]
+        auth_wrapper = options[:endpoint_auth_wrapper]
+
+        if auth_wrapper && auth_wrapper.method_defined?(:before) && !middleware.flatten.include?(auth_wrapper)
+          use auth_wrapper
+        end
 
         documentation_class.setup(options)
         mount(documentation_class)
@@ -80,7 +86,9 @@ module Grape
                end
           # use the full namespace here (not the latest level only)
           # and strip leading slash
-          @target_class.combined_namespaces[endpoint.namespace.sub(/^\//, '')] = ns if ns
+          mount_path = (endpoint.namespace_stackable(:mount_path) || []).join('/')
+          full_namespace = (mount_path + endpoint.namespace).sub(/\/{2,}/, '/').sub(/^\//, '')
+          @target_class.combined_namespaces[full_namespace] = ns if ns
 
           combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
         end

data/lib/grape-swagger/doc_methods.rb

@@ -31,37 +31,38 @@ module GrapeSwagger
       # options could be set on #add_swagger_documentation call,
       # for available options see #defaults
       target_class     = options[:target_class]
-      api_doc          = options[:api_documentation].dup
-      specific_api_doc = options[:specific_api_documentation].dup
+      guard            = options[:swagger_endpoint_guard]
+      formatter        = options[:format]
 
       class_variables_from(options)
 
       [:format, :default_format, :default_error_formatter].each do |method|
-        send(method, options[:format])
-      end if options[:format]
-      # getting of the whole swagger2.0 spec file
-      desc api_doc.delete(:desc), api_doc
-      get mount_path do
-        header['Access-Control-Allow-Origin']   = '*'
-        header['Access-Control-Request-Method'] = '*'
+        send(method, formatter)
+      end if formatter
 
-        output = swagger_object(
+      send(guard.split.first.to_sym, *guard.split(/[\s,]+/).drop(1)) unless guard.nil?
+
+      output_path_definitions = proc do |combi_routes, endpoint|
+        output = endpoint.swagger_object(
           target_class,
-          request,
+          endpoint.request,
           options
         )
 
-        target_routes        = target_class.combined_namespace_routes
-        paths, definitions   = path_and_definition_objects(target_routes, options)
+        paths, definitions = endpoint.path_and_definition_objects(combi_routes, options)
         output[:paths]       = paths unless paths.blank?
         output[:definitions] = definitions unless definitions.blank?
 
         output
       end
 
-      # getting of a specific/named route of the swagger2.0 spec file
-      desc specific_api_doc.delete(:desc), { params:
-        specific_api_doc.delete(:params) || {} }.merge(specific_api_doc)
+      get mount_path do
+        header['Access-Control-Allow-Origin']   = '*'
+        header['Access-Control-Request-Method'] = '*'
+
+        output_path_definitions.call(target_class.combined_namespace_routes, self)
+      end
+
       params do
         requires :name, type: String, desc: 'Resource name of mounted API'
         optional :locale, type: Symbol, desc: 'Locale of API documentation'
@@ -72,18 +73,7 @@ module GrapeSwagger
         combined_routes = target_class.combined_namespace_routes[params[:name]]
         error!({ error: 'named resource not exist' }, 400) if combined_routes.nil?
 
-        output = swagger_object(
-          target_class,
-          request,
-          options
-        )
-
-        target_routes        = { params[:name] => combined_routes }
-        paths, definitions   = path_and_definition_objects(target_routes, options)
-        output[:paths]       = paths unless paths.blank?
-        output[:definitions] = definitions unless definitions.blank?
-
-        output
+        output_path_definitions.call({ params[:name] => combined_routes }, self)
       end
     end
 
@@ -104,7 +94,10 @@ module GrapeSwagger
         authorizations: nil,
         security_definitions: nil,
         api_documentation: { desc: 'Swagger compatible API description' },
-        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }
+        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
+        endpoint_auth_wrapper: nil,
+        swagger_endpoint_guard: nil,
+        oauth_token: nil
       }
     end
 

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

@@ -66,6 +66,7 @@ module GrapeSwagger
               param_type = value_type[:documentation][:param_type]
               doc_type = value_type[:documentation][:type]
               type = GrapeSwagger::DocMethods::DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
+              collection_format = value_type[:documentation][:collectionFormat]
             end
 
             array_items = {
@@ -76,6 +77,7 @@ module GrapeSwagger
             @parsed_param[:in] = param_type || 'formData'
             @parsed_param[:items] = array_items
             @parsed_param[:type] = 'array'
+            @parsed_param[:collectionFormat] = collection_format if %w(csv ssv tsv pipes multi).include?(collection_format)
           end
         end
 

data/lib/grape-swagger/endpoint.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support'
 require 'active_support/core_ext/string/inflections.rb'
 
@@ -84,7 +86,7 @@ module Grape
     # path object
     def path_item(routes, options)
       routes.each do |route|
-        next if hidden?(route)
+        next if hidden?(route, options)
 
         @item, path = GrapeSwagger::DocMethods::PathString.build(route, options)
         @entity = route.entity || route.options[:success]
@@ -108,6 +110,7 @@ module Grape
       method[:produces]    = produces_object(route, options[:produces] || options[:format])
       method[:consumes]    = consumes_object(route, options[:format])
       method[:parameters]  = params_object(route)
+      method[:security]    = security_object(route)
       method[:responses]   = response_object(route, options[:markdown])
       method[:tags]        = tag_object(route)
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
@@ -116,6 +119,10 @@ module Grape
       [route.request_method.downcase.to_sym, method]
     end
 
+    def security_object(route)
+      route.options[:security] if route.options.key?(:security)
+    end
+
     def summary_object(route)
       summary = route.options[:desc] if route.options.key?(:desc)
       summary = route.description if route.description.present?
@@ -215,15 +222,17 @@ module Grape
       declared_params = route.settings[:declared_params] if route.settings[:declared_params].present?
       required, exposed = route.params.partition { |x| x.first.is_a? String }
       required = GrapeSwagger::DocMethods::Headers.parse(route) + required unless route.headers.nil?
+
       default_type(required)
       default_type(exposed)
 
-      unless declared_params.nil? && route.headers.nil?
-        request_params = parse_request_params(required)
-      end
+      request_params = unless declared_params.nil? && route.headers.nil?
+                         parse_request_params(required)
+                       end || {}
+
+      request_params = route.params.merge(request_params) if route.params.present? && !route.settings[:declared_params].present?
 
-      return route.params if route.params.present? && !route.settings[:declared_params].present?
-      request_params || {}
+      request_params
     end
 
     def default_type(params)
@@ -279,13 +288,23 @@ module Grape
     end
 
     def model_name(name)
-      name.respond_to?(:name) ? name.name.demodulize.camelize : name.split('::').last
+      if name.respond_to?(:entity_name)
+        name.entity_name
+      elsif name.to_s.end_with?('Entity', 'Entities')
+        length = 0
+        name.to_s.split('::')[0..-2].reverse.take_while do |x|
+          length += x.length
+          length < 42
+        end.reverse.join
+      else
+        name.name.demodulize.camelize
+      end
     end
 
-    def hidden?(route)
+    def hidden?(route, options)
       route_hidden = route.options[:hidden]
-      route_hidden = route_hidden.call if route_hidden.is_a?(Proc)
-      route_hidden
+      return route_hidden unless route_hidden.is_a?(Proc)
+      options[:oauth_token] ? route_hidden.call(send(options[:oauth_token].to_sym)) : route_hidden.call
     end
 
     def public_parameter?(param)

data/lib/grape-swagger/rake/oapi_tasks.rb

@@ -0,0 +1,99 @@
+require 'rake'
+require 'rake/tasklib'
+require 'rack/test'
+
+module GrapeSwagger
+  module Rake
+    class OapiTasks < ::Rake::TaskLib
+      include Rack::Test::Methods
+
+      attr_reader :oapi
+      attr_reader :api_class
+
+      def initialize(api_class)
+        super()
+
+        @api_class = api_class
+        define_tasks
+      end
+
+      private
+
+      def define_tasks
+        namespace :oapi do
+          fetch
+          validate
+        end
+      end
+
+      # tasks
+      #
+      # get swagger/OpenAPI documentation
+      def fetch
+        desc 'generates OpenApi documentation …
+          params (usage: key=value):
+          store    – save as JSON file, default: false            (optional)
+          resource - if given only for that it would be generated (optional)'
+        task fetch: :environment do
+          make_request
+
+          save_to_file? ? File.write(file, @oapi) : $stdout.print(@oapi)
+        end
+      end
+
+      # validates swagger/OpenAPI documentation
+      def validate
+        desc 'validates the generated OpenApi file …
+          params (usage: key=value):
+          resource - if given only for that it would be generated (optional)'
+        task validate: :environment do
+          ENV['store'] = 'true'
+          ::Rake::Task['oapi:fetch'].invoke
+          exit if error?
+
+          output = system "swagger validate #{file}"
+
+          $stdout.puts 'install swagger-cli with `npm install swagger-cli -g`' if output.nil?
+          FileUtils.rm(file)
+        end
+      end
+
+      # helper methods
+      #
+      def make_request
+        get url_for
+        last_response
+        @oapi = JSON.pretty_generate(
+          JSON.parse(
+            last_response.body, symolize_names: true
+          )
+        ) + "\n"
+      end
+
+      def url_for
+        oapi_route = api_class.routes[-2]
+        path = oapi_route.path.sub(/\(\.\w+\)$/, '').sub(/\(\.:\w+\)$/, '')
+        path.sub!(':version', oapi_route.version.to_s)
+
+        [path, ENV['resource']].join('/').chomp('/')
+      end
+
+      def save_to_file?
+        ENV['store'].present? && !error?
+      end
+
+      def error?
+        JSON.parse(@oapi).keys.first == 'error'
+      end
+
+      def file
+        name = ENV['store'] == 'true' || ENV['store'].blank? ? 'swagger_doc.json' : ENV['store']
+        File.join(Dir.getwd, name)
+      end
+
+      def app
+        api_class.new
+      end
+    end
+  end
+end

data/lib/grape-swagger/version.rb

@@ -1,3 +1,3 @@
 module GrapeSwagger
-  VERSION = '0.23.0'.freeze
+  VERSION = '0.24.0'.freeze
 end

data/spec/issues/430_entity_definitions_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+require 'grape-entity'
+require 'grape-swagger-entity'
+
+describe 'definition names' do
+  before :all do
+    module TestDefinition
+      module DummyEntities
+        module WithVeryLongName
+          module AnotherGroupingModule
+            class Class1
+              class Entity < Grape::Entity
+                expose :one_thing
+              end
+            end
+
+            class Class2
+              class Entity < Grape::Entity
+                expose :another_thing
+
+                def self.entity_name
+                  'FooKlass'
+                end
+              end
+            end
+          end
+        end
+      end
+
+      class NameApi < Grape::API
+        add_swagger_documentation models: [
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class1::Entity,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class2::Entity
+        ]
+      end
+    end
+  end
+
+  let(:app) { TestDefinition::NameApi }
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['definitions']
+  end
+
+  specify { expect(subject).to include 'AnotherGroupingModuleClass1' }
+  specify { expect(subject).to include 'FooKlass' }
+end

data/spec/lib/oapi_tasks_spec.rb

@@ -0,0 +1,133 @@
+require 'spec_helper'
+
+RSpec.describe GrapeSwagger::Rake::OapiTasks do
+  let(:api) do
+    item = Class.new(Grape::API) do
+      version 'v1', using: :path
+
+      resource :item do
+        get '/'
+      end
+
+      resource :otherItem do
+        get '/'
+      end
+    end
+
+    Class.new(Grape::API) do
+      prefix :api
+      mount item
+      add_swagger_documentation add_version: true
+    end
+  end
+
+  subject { described_class.new(api) }
+
+  describe '#make_request' do
+    describe 'complete documentation' do
+      before do
+        subject.send(:make_request)
+      end
+
+      describe 'not storing' do
+        it 'has no error' do
+          expect(subject.send(:error?)).to be false
+        end
+
+        it 'does not allow to save' do
+          expect(subject.send(:save_to_file?)).to be false
+        end
+
+        it 'requests doc url' do
+          expect(subject.send(:url_for)).to eql '/api/swagger_doc'
+        end
+      end
+
+      describe 'store it' do
+        before { ENV['store'] = 'true' }
+        after { ENV.delete('store') }
+
+        it 'allows to save' do
+          expect(subject.send(:save_to_file?)).to be true
+        end
+      end
+    end
+
+    describe 'documentation for resource' do
+      before do
+        ENV['resource'] = resource
+        subject.send(:make_request)
+      end
+
+      let(:response) { JSON.parse(subject.send(:make_request)) }
+
+      after { ENV.delete('resource') }
+
+      describe 'valid name' do
+        let(:resource) { 'otherItem' }
+
+        it 'has no error' do
+          expect(subject.send(:error?)).to be false
+        end
+
+        it 'requests doc url' do
+          expect(subject.send(:url_for)).to eql "/api/swagger_doc/#{resource}"
+        end
+
+        it 'has only one resource path' do
+          expect(response['paths'].length).to eql 1
+          expect(response['paths'].keys.first).to end_with resource
+        end
+      end
+
+      describe 'wrong name' do
+        let(:resource) { 'foo' }
+
+        it 'has error' do
+          expect(subject.send(:error?)).to be true
+        end
+      end
+
+      describe 'empty name' do
+        let(:resource) { nil }
+
+        it 'has no error' do
+          expect(subject.send(:error?)).to be false
+        end
+
+        it 'returns complete doc' do
+          expect(response['paths'].length).to eql 2
+        end
+      end
+    end
+  end
+
+  describe '#file' do
+    describe 'no store given' do
+      it 'returns swagger_doc.json' do
+        expect(subject.send(:file)).to end_with 'swagger_doc.json'
+      end
+    end
+
+    describe 'store given' do
+      after { ENV.delete('store') }
+
+      describe 'boolean true' do
+        before { ENV['store'] = 'true' }
+
+        it 'returns swagger_doc.json' do
+          expect(subject.send(:file)).to end_with 'swagger_doc.json'
+        end
+      end
+
+      describe 'name given' do
+        let(:name) { 'oapi_doc.json' }
+        before { ENV['store'] = name }
+
+        it 'returns swagger_doc.json' do
+          expect(subject.send(:file)).to end_with name
+        end
+      end
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_body_definitions_spec.rb

@@ -39,6 +39,8 @@ describe 'body parameter definitions' do
         'body_param' => { 'type' => 'string', 'description' => 'param' },
         'body_type_as_const_param' => { 'type' => 'string', 'description' => 'string_param' }
       )
+
+      expect(subject['paths']['/endpoint']['post']['parameters'].any? { |p| p['name'] == 'XAuthToken' && p['in'] == 'header' }).to eql(true)
     end
   end
 end

data/spec/swagger_v2/description_not_initialized.rb

@@ -2,8 +2,6 @@ require 'spec_helper'
 
 describe 'details' do
   describe 'details, pass markdown with redcarpet even with nil description and detail', unless: RUBY_PLATFORM.eql?('java') do
-    include_context 'the api entities'
-
     before :all do
       module TheApi
         class GfmRcDetailApi < Grape::API

data/spec/swagger_v2/guarded_endpoint_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+class SampleAuth < Grape::Middleware::Base
+  module AuthMethods
+    attr_accessor :access_token
+
+    def protected_endpoint=(protected)
+      @protected_endpoint = protected
+    end
+
+    def protected_endpoint?
+      @protected_endpoint || false
+    end
+
+    def access_token
+      @_access_token
+    end
+
+    def access_token=(token)
+      @_access_token = token
+    end
+  end
+
+  def context
+    env['api.endpoint']
+  end
+
+  def before
+    context.extend(SampleAuth::AuthMethods)
+    context.protected_endpoint = context.options[:route_options][:auth].present?
+
+    return unless context.protected_endpoint?
+    scopes = context.options[:route_options][:auth][:scopes].map(&:to_sym)
+    authorize!(*scopes) unless scopes.include? :false
+    context.access_token = env['HTTP_AUTHORIZATION']
+  end
+end
+
+module Extension
+  def sample_auth(*scopes)
+    description = route_setting(:description) || route_setting(:description, {})
+    description[:auth] = { scopes: scopes }
+  end
+
+  Grape::API.extend self
+end
+
+describe 'a guarded api endpoint' do
+  before :all do
+    class GuardedMountedApi < Grape::API
+      access_token_valid = proc { |token = nil| token.nil? || token != '12345' }
+
+      desc 'Show endpoint if authenticated', hidden: access_token_valid
+      get '/auth' do
+        { foo: 'bar' }
+      end
+    end
+
+    class GuardedApi < Grape::API
+      mount GuardedMountedApi
+      add_swagger_documentation endpoint_auth_wrapper: SampleAuth,
+                                swagger_endpoint_guard: 'sample_auth false',
+                                oauth_token: 'access_token'
+    end
+  end
+
+  def app
+    GuardedApi
+  end
+
+  context 'when a correct token is passed with the request' do
+    subject do
+      get '/swagger_doc.json', {}, 'HTTP_AUTHORIZATION' => '12345'
+      JSON.parse(last_response.body)
+    end
+
+    it 'retrieves swagger-documentation for the endpoint' do
+      expect(subject).to eq(
+        'info' => { 'title' => 'API title', 'version' => '0.0.1' },
+        'swagger' => '2.0',
+        'produces' => ['application/xml', 'application/json', 'application/octet-stream', 'text/plain'],
+        'host' => 'example.org',
+        'paths' => {
+          '/auth' => {
+            'get' => {
+              'summary' => 'Show endpoint if authenticated',
+              'description' => 'Show endpoint if authenticated',
+              'produces' => ['application/json'],
+              'tags' => ['auth'],
+              'operationId' => 'getAuth',
+              'responses' => { '200' => { 'description' => 'Show endpoint if authenticated' } }
+            }
+          }
+        }
+      )
+    end
+  end
+
+  context 'when a bad token is passed with the request' do
+    subject do
+      get '/swagger_doc.json', {}, 'HTTP_AUTHORIZATION' => '123456'
+      JSON.parse(last_response.body)
+    end
+
+    it 'does not retrieve swagger-documentation for the endpoint - only the info_object' do
+      expect(subject).to eq(
+        'info' => { 'title' => 'API title', 'version' => '0.0.1' },
+        'swagger' => '2.0',
+        'produces' => ['application/xml', 'application/json', 'application/octet-stream', 'text/plain'],
+        'host' => 'example.org'
+      )
+    end
+  end
+end

data/spec/swagger_v2/host.rb

@@ -1,8 +1,6 @@
 require 'spec_helper'
 
 describe 'host in the swagger_doc' do
-  include_context 'the api entities'
-
   before :all do
     module TheApi
       class EmptyApi < Grape::API

data/spec/swagger_v2/namespaced_api_spec.rb

@@ -64,4 +64,56 @@ describe 'namespace' do
       expect(subject['description']).to eql('Description for aspace')
     end
   end
+
+  context 'mounted under a route' do
+    def app
+      namespaced_api = Class.new(Grape::API) do
+        namespace :bspace do
+          get '/', desc: 'Description for aspace'
+        end
+      end
+
+      Class.new(Grape::API) do
+        mount namespaced_api => '/mounted'
+        add_swagger_documentation format: :json
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['paths']['/mounted/bspace']['get']
+    end
+
+    it 'shows the namespace description in the json spec' do
+      expect(subject['description']).to eql('Description for aspace')
+    end
+  end
+
+  context 'arbitrary mounting' do
+    def app
+      inner_namespaced_api = Class.new(Grape::API) do
+        namespace :bspace do
+          get '/', desc: 'Description for aspace'
+        end
+      end
+
+      outer_namespaced_api = Class.new(Grape::API) do
+        mount inner_namespaced_api => '/mounted'
+      end
+
+      Class.new(Grape::API) do
+        mount outer_namespaced_api => '/'
+        add_swagger_documentation format: :json
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['paths']['/mounted/bspace']['get']
+    end
+
+    it 'shows the namespace description in the json spec' do
+      expect(subject['description']).to eql('Description for aspace')
+    end
+  end
 end

data/spec/swagger_v2/params_array_collection_fromat_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+describe 'Group Array Params, using collection format' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        optional :array_of_strings, type: Array[String], desc: 'array in csv collection format'
+      end
+
+      get '/array_of_strings_without_collection_format' do
+        { 'declared_params' => declared(params) }
+      end
+
+      params do
+        optional :array_of_strings, type: Array[String], desc: 'array in multi collection format', documentation: { collectionFormat: 'multi' }
+      end
+
+      get '/array_of_strings_multi_collection_format' do
+        { 'declared_params' => declared(params) }
+      end
+
+      params do
+        optional :array_of_strings, type: Array[String], documentation: { collectionFormat: 'foo' }
+      end
+
+      get '/array_of_strings_invalid_collection_format' do
+        { 'declared_params' => declared(params) }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  describe 'documentation for array parameter in default csv collectionFormat' do
+    subject do
+      get '/swagger_doc/array_of_strings_without_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_without_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false, 'description' => 'array in csv collection format' }
+        ]
+      )
+    end
+  end
+
+  describe 'documentation for array parameters in multi collectionFormat set from documentation' do
+    subject do
+      get '/swagger_doc/array_of_strings_multi_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_multi_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false, 'collectionFormat' => 'multi', 'description' => 'array in multi collection format' }
+        ]
+      )
+    end
+  end
+
+  describe 'documentation for array parameters with collectionFormat set to invalid option' do
+    subject do
+      get '/swagger_doc/array_of_strings_invalid_collection_format'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/array_of_strings_invalid_collection_format']['get']['parameters']).to eql(
+        [
+          { 'in' => 'formData', 'name' => 'array_of_strings', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false }
+        ]
+      )
+    end
+  end
+end

data/spec/swagger_v2/security_requirement_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe 'security requirement on endpoint method' do
+  def app
+    Class.new(Grape::API) do
+      desc 'Endpoint with security requirement', security: [oauth_pets: ['read:pets', 'write:pets']]
+      get '/with_security' do
+        { foo: 'bar' }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body)
+  end
+
+  it 'defines the security requirement on the endpoint method' do
+    expect(subject['paths']['/with_security']['get']['security']).to eql ['oauth_pets' => ['read:pets', 'write:pets']]
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Tim Vandecasteele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-05 00:00:00.000000000 Z
+date: 2016-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -255,13 +255,16 @@ files:
 - lib/grape-swagger/markdown/kramdown_adapter.rb
 - lib/grape-swagger/markdown/redcarpet_adapter.rb
 - lib/grape-swagger/model_parsers.rb
+- lib/grape-swagger/rake/oapi_tasks.rb
 - lib/grape-swagger/version.rb
 - spec/issues/403_versions_spec.rb
+- spec/issues/430_entity_definitions_spec.rb
 - spec/lib/data_type_spec.rb
 - spec/lib/endpoint_spec.rb
 - spec/lib/extensions_spec.rb
 - spec/lib/model_parsers_spec.rb
 - spec/lib/move_params_spec.rb
+- spec/lib/oapi_tasks_spec.rb
 - spec/lib/operation_id_spec.rb
 - spec/lib/optional_object_spec.rb
 - spec/lib/path_string_spec.rb
@@ -304,6 +307,7 @@ files:
 - spec/swagger_v2/float_api_spec.rb
 - spec/swagger_v2/form_params_spec.rb
 - spec/swagger_v2/grape-swagger_spec.rb
+- spec/swagger_v2/guarded_endpoint_spec.rb
 - spec/swagger_v2/hide_api_spec.rb
 - spec/swagger_v2/host.rb
 - spec/swagger_v2/mounted_target_class_spec.rb
@@ -314,10 +318,12 @@ files:
 - spec/swagger_v2/param_multi_type_spec.rb
 - spec/swagger_v2/param_type_spec.rb
 - spec/swagger_v2/param_values_spec.rb
+- spec/swagger_v2/params_array_collection_fromat_spec.rb
 - spec/swagger_v2/params_array_spec.rb
 - spec/swagger_v2/params_hash_spec.rb
 - spec/swagger_v2/params_nested_spec.rb
 - spec/swagger_v2/reference_entity.rb
+- spec/swagger_v2/security_requirement_spec.rb
 - spec/swagger_v2/simple_mounted_api_spec.rb
 - spec/version_spec.rb
 homepage: https://github.com/ruby-grape/grape-swagger
@@ -340,18 +346,20 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.4
+rubygems_version: 2.6.6
 signing_key: 
 specification_version: 4
 summary: A simple way to add auto generated documentation to your Grape API that can
   be displayed with Swagger.
 test_files:
 - spec/issues/403_versions_spec.rb
+- spec/issues/430_entity_definitions_spec.rb
 - spec/lib/data_type_spec.rb
 - spec/lib/endpoint_spec.rb
 - spec/lib/extensions_spec.rb
 - spec/lib/model_parsers_spec.rb
 - spec/lib/move_params_spec.rb
+- spec/lib/oapi_tasks_spec.rb
 - spec/lib/operation_id_spec.rb
 - spec/lib/optional_object_spec.rb
 - spec/lib/path_string_spec.rb
@@ -394,6 +402,7 @@ test_files:
 - spec/swagger_v2/float_api_spec.rb
 - spec/swagger_v2/form_params_spec.rb
 - spec/swagger_v2/grape-swagger_spec.rb
+- spec/swagger_v2/guarded_endpoint_spec.rb
 - spec/swagger_v2/hide_api_spec.rb
 - spec/swagger_v2/host.rb
 - spec/swagger_v2/mounted_target_class_spec.rb
@@ -404,9 +413,11 @@ test_files:
 - spec/swagger_v2/param_multi_type_spec.rb
 - spec/swagger_v2/param_type_spec.rb
 - spec/swagger_v2/param_values_spec.rb
+- spec/swagger_v2/params_array_collection_fromat_spec.rb
 - spec/swagger_v2/params_array_spec.rb
 - spec/swagger_v2/params_hash_spec.rb
 - spec/swagger_v2/params_nested_spec.rb
 - spec/swagger_v2/reference_entity.rb
+- spec/swagger_v2/security_requirement_spec.rb
 - spec/swagger_v2/simple_mounted_api_spec.rb
 - spec/version_spec.rb