grape-swagger 1.3.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a3f65f49a31d6affe69a657daff3867582070436163992acb47f1166dde1cc6
-  data.tar.gz: da9f13e2efd7e2b23dc92eea5b9deeaf4d9b8a860b13bae2b7f928b31d996be3
+  metadata.gz: 5d7b364d5b11e9fb35f7c67ce09c2953a7dd50da37cde1bc5b323bbdf9a3b6e4
+  data.tar.gz: 6c825fe6753c899c7f337253495677596acd40320e5e33f83c7c220e71e03e44
 SHA512:
-  metadata.gz: 0d51d5cde5ff558fefcbf8b4503d290bc535c48f22d1ee3c2662ad406c548b7ef72d196b36598b2d3ea68d6ebef8e6ce43e3dec8dab6f371df9d12aaadd34567
-  data.tar.gz: b22301456da8cd150767fd614434bfad161959eb0836b028b4ff8d15893fd128c53513e87ab8180a6442b8fda9ec41a6e6648b67cb32a46b692d2b117e229ec1
+  metadata.gz: d5e2a5c0d06216c3e2a474051b5986a9f8343a351714b3e255396bbef3984704d85436218fa87e39f0988fbb18b3f5227b2531d514a788f4a4b131028dc19de2
+  data.tar.gz: 6bd210a20332285224d0d24036b9892c729fc84c435991b3e36dd81d8d1976d4ae35c406d3e9d742a82bd90acac75903355c6a827380870e6f1deb2af0b17b7f

data/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "bundler" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+      day: "friday"
+    assignees:
+      - "LeFnord"

data/.github/workflows/rubocop.yml

@@ -0,0 +1,26 @@
+name: Rubocop
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  rubocop:
+    name: Rubocop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+      - run: gem install rubocop --no-doc
+      - run: rubocop --format progress --format json --out rubocop.json
+        id: rubocop
+      - uses: duderman/rubocop-annotate-action@v0.1.0
+        with:
+          path: rubocop.json
+        if: ${{ failure() }}

data/.github/workflows/ruby.yml

@@ -0,0 +1,30 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  rspec:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0', 'head']
+        grape-version: [1.6.0, 1.5.3]
+        model-parser: [grape-swagger-entity, grape-swagger-representable, '']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        GRAPE_VERSION: ${{ matrix.grape-version }}
+        MODEL_PARSER: ${{ matrix.model-parser }}
+        bundler-cache: true
+    - name: Run rspec
+      run: bundle exec rspec

data/.gitignore

@@ -42,3 +42,4 @@ spec/params_entity_spec.rb
 vendor/bundle/
 spec/swagger_v2/x-dummy.rb
 coverage/
+.byebug_history

data/.rspec

@@ -1 +1,3 @@
 --color
+--profile
+--format documentation

data/.rubocop.yml

@@ -5,7 +5,8 @@ AllCops:
     - vendor/**/*
     - example/**/*
   NewCops: enable
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
 
 #  Layout stuff
 #
@@ -28,6 +29,10 @@ Layout/SpaceAroundMethodCallOperator:
 
 # Lint stuff
 #
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/**/*
+
 Lint/DeprecatedOpenSSLConstant:
   Enabled: true
 
@@ -50,7 +55,7 @@ Metrics/BlockLength:
     - spec/**/*
 
 Metrics/ClassLength:
-  Max: 300
+  Max: 350
 
 Metrics/CyclomaticComplexity:
   Max: 17
@@ -69,6 +74,9 @@ Naming:
 Style/AccessorGrouping:
   Enabled: true
 
+Style/AsciiComments:
+  Enabled: false
+
 Style/ArrayCoercion:
   Enabled: true
 

data/.rubocop_todo.yml

@@ -28,7 +28,7 @@ Metrics/MethodLength:
 
 # Offense count: 7
 Metrics/PerceivedComplexity:
-  Max: 14
+  Max: 16
 
 # Offense count: 3
 Style/ClassVars:

data/CHANGELOG.md

@@ -9,6 +9,45 @@
 * Your contribution here.
 
 
+### 1.4.2 (October 22, 2021)
+
+#### Fixes
+
+* [#840](https://github.com/ruby-grape/grape-swagger/pull/840): Fixes documentation of `additionalProperties` field when used with array parameters, or when setting it to `false` - [@magni-](https://github.com/magni-)
+* [#841](https://github.com/ruby-grape/grape-swagger/pull/839): Fixes `type` and `format` values for object fields nested in an array ([#832](https://github.com/ruby-grape/grape-swagger/issue/832)) - [@magni-](https://github.com/magni-)
+* [#839](https://github.com/ruby-grape/grape-swagger/pull/839): Fixes documentation of `false` or `nil` default parameter values - [@magni-](https://github.com/magni-)
+
+
+### 1.4.1 (September 15, 2021)
+
+#### Fixes
+
+* [#833](https://github.com/ruby-grape/grape-swagger/pull/833): Fixes issue of examples not showing for `in: 'body'` parameters - [@stevenou](https://github.com/stevenou)
+
+
+### 1.4.0 (March 20, 2021)
+
+#### Features
+
+* [#818](https://github.com/ruby-grape/grape-swagger/pull/818): Adds ruby 3.0 support - [@LeFnord](https://github.com/LeFnord).
+* [#815](https://github.com/ruby-grape/grape-swagger/pull/815): Add required for multiple presents - [@MaximeRDY](https://github.com/MaximeRDY).
+
+#### Fixes
+
+* [#822](https://github.com/ruby-grape/grape-swagger/pull/822): Corrected the related parameter lookup on request params - [@Jack12816](https://github.com/Jack12816).
+
+
+### 1.3.1 (November 1, 2020)
+
+#### Features
+
+* [#813](https://github.com/ruby-grape/grape-swagger/pull/813): Handle multiple presents - [@AntoineGuestin](https://github.com/AntoineGuestin).
+
+#### Fixes
+
+* [#811](https://github.com/ruby-grape/grape-swagger/pull/811): Fixes #809: supports utf8 route names - [@LeFnord](https://github.com/LeFnord).
+
+
 ### 1.3.0 (September 3, 2020)
 
 #### Features

data/Gemfile

@@ -6,7 +6,7 @@ ruby RUBY_VERSION
 
 gemspec
 
-gem 'grape', case version = ENV['GRAPE_VERSION'] || '>= 1.4.0'
+gem 'grape', case version = ENV['GRAPE_VERSION'] || '>= 1.5.0'
              when 'HEAD'
                { git: 'https://github.com/ruby-grape/grape' }
              else
@@ -27,13 +27,13 @@ group :development, :test do
   gem 'rake'
   gem 'rdoc'
   gem 'rspec', '~> 3.9'
-  gem 'rubocop', '~> 0.90', require: false
+  gem 'rubocop', '~> 1.0', require: false
 end
 
 group :test do
   gem 'coveralls_reborn', require: false
 
-  gem 'ruby-grape-danger', '~> 0.1.1', require: false
+  gem 'ruby-grape-danger', '~> 0.2.0', require: false
   gem 'simplecov', require: false
 
   unless ENV['MODEL_PARSER'] == 'grape-swagger-entity'

data/README.md

@@ -451,6 +451,8 @@ add_swagger_documentation \
 * [Collection Format](#collection-format)
 * [Hiding parameters](#hiding-parameters)
 * [Setting a Swagger default value](#default-value)
+* [Setting `additionalProperties` for `object`-type parameters](#additional-properties)
+* [Example parameter value](#param-example)
 * [Response documentation](#response)
 * [Changing default status codes](#change-status)
 * [File response](#file-response)
@@ -458,6 +460,7 @@ add_swagger_documentation \
 * [Response examples documentation](#response-examples)
 * [Response headers documentation](#response-headers)
 * [Adding root element to responses](#response-root)
+* [Multiple present Response](#multiple-response)
 
 #### Swagger Header Parameters  <a name="headers"></a>
 
@@ -768,8 +771,6 @@ params do
 end
 ```
 
-The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
-
 Grape uses the option `default` to set a default value for optional parameters. This is different in that Grape will set your parameter to the provided default if the parameter is omitted, whereas the example value above will only set the value in the UI itself. This will set the Swagger `defaultValue` to the provided value. Note that the example value will override the Grape default value.
 
 ```ruby
@@ -779,6 +780,46 @@ params do
 end
 ```
 
+### Setting `additionalProperties` for `object`-type parameters <a name="additional-properties">
+
+Use the `additional_properties` option in the `documentation` hash for `object`-type parameters to set [`additionalProperties`](https://swagger.io/specification/v2/#model-with-mapdictionary-properties).
+
+#### Allow any additional properties
+```ruby
+params do
+  optional :thing, type: Hash, documentation: { additional_properties: true }
+end
+```
+
+#### Allow any additional properties of a particular type
+```ruby
+params do
+  optional :thing, type: Hash, documentation: { additional_properties: String }
+end
+```
+
+#### Allow any additional properties matching a defined schema
+```ruby
+class Entity < Grape::Entity
+  expose :this
+end
+
+params do
+  optional :thing, type: Hash, documentation: { additional_properties: Entity }
+end
+```
+
+
+#### Example parameter value <a name="param-example"></a>
+
+The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
+
+```ruby
+params do
+  requires :id, type: Integer, documentation: { example: 123 }
+  optional :name, type String, documentation: { example: 'Buddy Guy' }
+end
+```
 
 #### Expose nested namespace as standalone route
 
@@ -1262,6 +1303,76 @@ The result will look like following:
     }
   }
 ```
+#### Multiple present Response <a name="multiple-response"></a>
+
+You can specify a custom multiple response by using the `as` key:
+```ruby
+desc 'Multiple response',
+  success: [
+    { model: Entities::EnumValues, as: :gender },
+    { model: Entities::Something, as: :somethings }
+  ]
+end
+
+get '/things' do
+  ...
+end
+```
+The result will look like following:
+```
+  "responses": {
+    "200": {
+      "description": "Multiple response",
+      "schema":{
+        "type":"object",
+        "properties":{
+          "gender":{
+            "$ref":"#/definitions/EnumValues"
+          },
+          "somethings":{
+            "$ref":"#/definitions/Something"
+          }
+        }
+      }
+    }
+  }
+```
+You can also specify if the response is an array, with the `is_array` key:
+```ruby
+desc 'Multiple response with array',
+  success: [
+    { model: Entities::EnumValues, as: :gender },
+    { model: Entities::Something, as: :somethings, is_array: true, required: true }
+  ]
+end
+
+get '/things' do
+  ...
+end
+```
+The result will look like following:
+```
+  "responses": {
+    "200": {
+      "description": "Multiple response with array",
+      "schema":{
+        "type":"object",
+        "properties":{
+          "gender":{
+            "$ref":"#/definitions/EnumValues"
+          },
+          "somethings":{
+            "type":"array",
+            "items":{
+                "$ref":"#/definitions/Something"
+            }
+          }
+        },
+        "required": ["somethings"]
+      }
+    }
+  }
+```
 
 ## Using Grape Entities <a name="grape-entity"></a>
 

data/UPGRADING.md

@@ -1,5 +1,13 @@
 ## Upgrading Grape-swagger
 
+### Upgrading to >= 1.4.2
+
+- `additionalProperties` has been deprecated and will be removed in a future version of `grape-swagger`. It has been replaced with `additional_properties`.
+
+### Upgrading to >= 1.4.0
+
+- Official support for ruby < 2.5 removed, ruby 2.5 only in testing mode, but no support.
+
 ### Upgrading to >= 1.3.0
 
 - The model (entity) description no longer comes from the route description. It will have a default value: `<<EntityName>> model`.

data/grape-swagger.gemspec

@@ -7,13 +7,13 @@ Gem::Specification.new do |s|
   s.name        = 'grape-swagger'
   s.version     = GrapeSwagger::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ['Tim Vandecasteele']
-  s.email       = ['tim.vandecasteele@gmail.com']
+  s.authors     = ['LeFnord', 'Tim Vandecasteele']
+  s.email       = ['pscholz.le@gmail.com', 'tim.vandecasteele@gmail.com']
   s.homepage    = 'https://github.com/ruby-grape/grape-swagger'
   s.summary     = 'Add auto generated documentation to your Grape API that can be displayed with Swagger.'
   s.license     = 'MIT'
 
-  s.required_ruby_version = '>= 2.4'
+  s.required_ruby_version = '>= 2.5'
   s.add_runtime_dependency 'grape', '~> 1.3'
 
   s.files         = `git ls-files`.split("\n")

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

@@ -7,7 +7,7 @@ module GrapeSwagger
         def to_format(parameters)
           parameters.reject { |parameter| parameter[:in] == 'body' }.each do |b|
             related_parameters = parameters.select do |p|
-              p[:name] != b[:name] && p[:name].to_s.include?("#{b[:name].to_s.gsub(/\[\]\z/, '')}[")
+              p[:name] != b[:name] && p[:name].to_s.start_with?("#{b[:name].to_s.gsub(/\[\]\z/, '')}[")
             end
             parameters.reject! { |p| p[:name] == b[:name] } if move_down(b, related_parameters)
           end
@@ -35,6 +35,8 @@ module GrapeSwagger
 
         def add_array(parameter, related_parameters)
           related_parameters.each do |p|
+            next if p.key?(:items)
+
             p_type = p[:type] == 'array' ? 'string' : p[:type]
             p[:items] = { type: p_type, format: p[:format], enum: p[:enum], is_array: p[:is_array] }
             p[:items].delete_if { |_k, v| v.nil? }

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

@@ -103,9 +103,9 @@ module GrapeSwagger
 
         def document_as_property(param)
           property_keys.each_with_object({}) do |x, memo|
-            value = param[x]
-            next if value.blank?
+            next unless param.key?(x)
 
+            value = param[x]
             if x == :type && @definitions[value].present?
               memo['$ref'] = "#/definitions/#{value}"
             else
@@ -181,7 +181,8 @@ module GrapeSwagger
         end
 
         def property_keys
-          %i[type format description minimum maximum items enum default additionalProperties]
+          %i[type format description minimum maximum items enum default additional_properties additionalProperties
+             example]
         end
 
         def deletable?(param)
@@ -193,8 +194,7 @@ module GrapeSwagger
         end
 
         def includes_body_param?(params)
-          params.map { |x| return true if x[:in] == 'body' || x[:param_type] == 'body' }
-          false
+          params.any? { |x| x[:in] == 'body' || x[:param_type] == 'body' }
         end
 
         def should_expose_as_array?(params)
@@ -202,8 +202,7 @@ module GrapeSwagger
         end
 
         def should_exposed_as(params)
-          params.map { |x| return 'object' if x[:type] && x[:type] != 'array' }
-          'array'
+          params.any? { |x| x[:type] && x[:type] != 'array' } ? 'object' : 'array'
         end
       end
     end

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

@@ -25,8 +25,9 @@ module GrapeSwagger
           document_default_value(settings) unless value_type[:is_array]
           document_range_values(settings) unless value_type[:is_array]
           document_required(settings)
-          document_additional_properties(settings)
+          document_additional_properties(definitions, settings) unless value_type[:is_array]
           document_add_extensions(settings)
+          document_example(settings)
 
           @parsed_param
         end
@@ -50,7 +51,7 @@ module GrapeSwagger
         end
 
         def document_default_value(settings)
-          @parsed_param[:default] = settings[:default] if settings[:default].present?
+          @parsed_param[:default] = settings[:default] if settings.key?(:default)
         end
 
         def document_type_and_format(settings, data_type)
@@ -104,12 +105,43 @@ module GrapeSwagger
 
           array_items[:default] = value_type[:default] if value_type[:default].present?
 
+          set_additional_properties, additional_properties = parse_additional_properties(definitions, value_type)
+          array_items[:additionalProperties] = additional_properties if set_additional_properties
+
           array_items
         end
 
-        def document_additional_properties(settings)
-          additional_properties = settings[:additionalProperties]
-          @parsed_param[:additionalProperties] = additional_properties if additional_properties
+        def document_additional_properties(definitions, settings)
+          set_additional_properties, additional_properties = parse_additional_properties(definitions, settings)
+          @parsed_param[:additionalProperties] = additional_properties if set_additional_properties
+        end
+
+        def parse_additional_properties(definitions, settings)
+          return false unless settings.key?(:additionalProperties) || settings.key?(:additional_properties)
+
+          value =
+            if settings.key?(:additionalProperties)
+              GrapeSwagger::Errors::SwaggerSpecDeprecated.tell!(:additionalProperties)
+              settings[:additionalProperties]
+            else
+              settings[:additional_properties]
+            end
+
+          parsed_value =
+            if definitions[value.to_s]
+              { '$ref': "#/definitions/#{value}" }
+            elsif value.is_a?(Class)
+              { type: DataType.call(value) }
+            else
+              value
+            end
+
+          [true, parsed_value]
+        end
+
+        def document_example(settings)
+          example = settings[:example]
+          @parsed_param[:example] = example if example
         end
 
         def param_type(value_type)

data/lib/grape-swagger/endpoint.rb

@@ -201,8 +201,7 @@ module Grape
     def response_object(route, options)
       codes(route).each_with_object({}) do |value, memo|
         value[:message] ||= ''
-        memo[value[:code]] = { description: value[:message] }
-
+        memo[value[:code]] = { description: value[:message] ||= '' } unless memo[value[:code]].present?
         memo[value[:code]][:headers] = value[:headers] if value[:headers]
 
         next build_file_response(memo[value[:code]]) if file_response?(value[:model])
@@ -221,7 +220,7 @@ module Grape
         next if response_model.start_with?('Swagger_doc')
 
         @definitions[response_model][:description] ||= "#{response_model} model"
-        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
+        build_memo_schema(memo, route, value, response_model, options)
         memo[value[:code]][:examples] = value[:examples] if value[:examples]
       end
     end
@@ -268,15 +267,52 @@ module Grape
 
     private
 
+    def build_memo_schema(memo, route, value, response_model, options)
+      if memo[value[:code]][:schema] && value[:as]
+        memo[value[:code]][:schema][:properties].merge!(build_reference(route, value, response_model, options))
+
+        if value[:required]
+          memo[value[:code]][:schema][:required] ||= []
+          memo[value[:code]][:schema][:required] << value[:as].to_s
+        end
+
+      elsif value[:as]
+        memo[value[:code]][:schema] = {
+          type: :object,
+          properties: build_reference(route, value, response_model, options)
+        }
+        memo[value[:code]][:schema][:required] = [value[:as].to_s] if value[:required]
+      else
+        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
+      end
+    end
+
     def build_reference(route, value, response_model, settings)
       # TODO: proof that the definition exist, if model isn't specified
-      reference = { '$ref' => "#/definitions/#{response_model}" }
+      reference = if value.key?(:as)
+                    { value[:as] => build_reference_hash(response_model) }
+                  else
+                    build_reference_hash(response_model)
+                  end
       return reference unless value[:code] < 300
 
-      reference = { type: 'array', items: reference } if route.options[:is_array]
+      if value.key?(:as) && value.key?(:is_array)
+        reference[value[:as]] = build_reference_array(reference[value[:as]])
+      elsif route.options[:is_array]
+        reference = build_reference_array(reference)
+      end
+
       build_root(route, reference, response_model, settings)
     end
 
+    def build_reference_hash(response_model)
+      { '$ref' => "#/definitions/#{response_model}" }
+    end
+
+    def build_reference_array(reference)
+      { type: 'array', items: reference }
+    end
+
     def build_root(route, reference, response_model, settings)
       default_root = response_model.underscore
       default_root = default_root.pluralize if route.options[:is_array]
@@ -293,7 +329,7 @@ module Grape
     end
 
     def file_response?(value)
-      value.to_s.casecmp('file').zero? ? true : false
+      value.to_s.casecmp('file').zero?
     end
 
     def build_file_response(memo)
@@ -382,6 +418,9 @@ module Grape
         default_code[:message] = entity[:message] || route.description || default_code[:message].sub('{item}', @item)
         default_code[:examples] = entity[:examples] if entity[:examples]
         default_code[:headers] = entity[:headers] if entity[:headers]
+        default_code[:as] = entity[:as] if entity[:as]
+        default_code[:is_array] = entity[:is_array] if entity[:is_array]
+        default_code[:required] = entity[:required] if entity[:required]
       else
         default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
         default_code[:model] = entity if entity

data/lib/grape-swagger/errors.rb

@@ -3,7 +3,9 @@
 module GrapeSwagger
   module Errors
     class UnregisteredParser < StandardError; end
+
     class SwaggerSpec < StandardError; end
+
     class SwaggerSpecDeprecated < SwaggerSpec
       class << self
         def tell!(what)

data/lib/grape-swagger/model_parsers.rb

@@ -16,14 +16,14 @@ module GrapeSwagger
       subhash = @parsers.except(klass).to_a
       insert_at = subhash.index(subhash.assoc(before_klass))
       insert_at = subhash.length - 1 if insert_at.nil?
-      @parsers = Hash[subhash.insert(insert_at, [klass, ancestor])]
+      @parsers = subhash.insert(insert_at, [klass, ancestor]).to_h
     end
 
     def insert_after(after_klass, klass, ancestor)
       subhash = @parsers.except(klass).to_a
       insert_at = subhash.index(subhash.assoc(after_klass))
       insert_at = subhash.length - 1 if insert_at.nil?
-      @parsers = Hash[subhash.insert(insert_at + 1, [klass, ancestor])]
+      @parsers = subhash.insert(insert_at + 1, [klass, ancestor]).to_h
     end
 
     def each

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

@@ -64,7 +64,7 @@ module GrapeSwagger
           ::Rake::Task['oapi:fetch'].invoke
           exit if error?
 
-          output = system "swagger validate #{file}"
+          output = system "swagger-cli validate #{file}"
 
           $stdout.puts 'install swagger-cli with `npm install swagger-cli -g`' if output.nil?
           FileUtils.rm(file)

data/lib/grape-swagger/version.rb

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