grape-swagger 1.1.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beb6baac3bba57a4fd27f01c8129fbd128c0c88426f1408784f1e77ef870c65a
-  data.tar.gz: 88234909ace085c8b63f0534630ae8856eb15d383bee856c9fcc57079d0060a1
+  metadata.gz: 5d7b364d5b11e9fb35f7c67ce09c2953a7dd50da37cde1bc5b323bbdf9a3b6e4
+  data.tar.gz: 6c825fe6753c899c7f337253495677596acd40320e5e33f83c7c220e71e03e44
 SHA512:
-  metadata.gz: 3b50e2b60fb3d4a1876bac4587f740c27a624c02726153746dc79e76fb1a233d04a3b1b15844bf65a337484d551ac6ea84b04c85c1537138dfc4327149cbb654
-  data.tar.gz: 32a0e9014bf782a0f5a5417a307bf9325986d7d9df662e73174525792e9103d2a3ec3c4f8b3d7fbdc72829d7514ba299dd62adb361085020f37b104f9a29ee25
+  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

@@ -4,13 +4,18 @@ AllCops:
   Exclude:
     - vendor/**/*
     - example/**/*
-  TargetRubyVersion: 2.7
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
 
 #  Layout stuff
 #
 Layout/EmptyLinesAroundArguments:
   Enabled: false
 
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
 Layout/FirstHashElementIndentation:
   EnforcedStyle: consistent
 
@@ -24,6 +29,19 @@ Layout/SpaceAroundMethodCallOperator:
 
 # Lint stuff
 #
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/**/*
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
 Lint/RaiseException:
   Enabled: true
 
@@ -37,7 +55,10 @@ Metrics/BlockLength:
     - spec/**/*
 
 Metrics/ClassLength:
-  Max: 300
+  Max: 350
+
+Metrics/CyclomaticComplexity:
+  Max: 17
 
 Metrics/MethodLength:
   Exclude:
@@ -50,12 +71,36 @@ Naming:
 
 # Style stuff
 #
+Style/AccessorGrouping:
+  Enabled: true
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/ArrayCoercion:
+  Enabled: true
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/CaseLikeIf:
+  Enabled: true
+
 Style/ExponentialNotation:
   Enabled: true
 
+Style/ExplicitBlockArgument:
+  Enabled: false
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
 Style/HashEachMethods:
   Enabled: true
 
+Style/HashLikeCase:
+  Enabled: true
+
 Style/HashTransformKeys:
   Enabled: true
 
@@ -64,3 +109,21 @@ Style/HashTransformValues:
 
 Style/RegexpLiteral:
   Enabled: false
+
+Style/RedundantAssignment:
+  Enabled: true
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: false

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,72 @@
 * 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
+
+* [#804](https://github.com/ruby-grape/grape-swagger/pull/804): Don't overwrite model description with the route description - [@Bhacaz](https://github.com/Bhacaz).
+
+
+### 1.2.1 (July 15, 2020)
+
+#### Fixes
+
+* [#801](https://github.com/ruby-grape/grape-swagger/pull/801): Fixes behaviour after grape upgrade to 1.4.0 - [@LeFnord](https://github.com/LeFnord).
+
+
+### 1.2.0 (July 1, 2020)
+
+#### Features
+
+* [#794](https://github.com/ruby-grape/grape-swagger/pull/794): Allow `entity_name` to be inherited, fixes issue #659 - [@urkle](https://github.com/urkle).
+* [#793](https://github.com/ruby-grape/grape-swagger/pull/793): Features/inheritance and discriminator - [@MaximeRDY](https://github.com/MaximeRDY).
+
+#### Fixes
+
+* [#798](https://github.com/ruby-grape/grape-swagger/pull/798): Modify full entity name separator - [@GarrettB71](https://github.com/GarrettB71).
+* [#796](https://github.com/ruby-grape/grape-swagger/pull/796): Support grape 1.4.0 - [@thedanielhanke](https://github.com/thedanielhanke).
+
+
 ### 1.1.0 (April 20, 2020)
 
 #### Features

data/Gemfile

@@ -6,7 +6,7 @@ ruby RUBY_VERSION
 
 gemspec
 
-gem 'grape', case version = ENV['GRAPE_VERSION'] || '>= 1.3.0'
+gem 'grape', case version = ENV['GRAPE_VERSION'] || '>= 1.5.0'
              when 'HEAD'
                { git: 'https://github.com/ruby-grape/grape' }
              else
@@ -14,6 +14,7 @@ gem 'grape', case version = ENV['GRAPE_VERSION'] || '>= 1.3.0'
              end
 
 gem ENV['MODEL_PARSER'] if ENV.key?('MODEL_PARSER')
+
 group :development, :test do
   gem 'bundler'
   gem 'grape-entity'
@@ -26,12 +27,16 @@ group :development, :test do
   gem 'rake'
   gem 'rdoc'
   gem 'rspec', '~> 3.9'
-  gem 'rubocop', '~> 0.82', require: false
+  gem 'rubocop', '~> 1.0', require: false
 end
 
 group :test do
   gem 'coveralls_reborn', require: false
-  gem 'grape-swagger-entity'
-  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'
+    gem 'grape-swagger-entity', git: 'https://github.com/ruby-grape/grape-swagger-entity'
+  end
 end

data/README.md

@@ -43,16 +43,16 @@ This screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sa
 
 The following versions of grape, grape-entity and grape-swagger can currently be used together.
 
-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.25.2        |     2.0      | >= 0.14.0 ... <= 0.18.0 | <= 0.6.0     | >= 2.4.1      |
-0.26.0        |     2.0      | >= 0.16.2 ... <= 1.1.0  | <= 0.6.1     | >= 2.4.1      |
-0.27.0        |     2.0      | >= 0.16.2 ... <= 1.1.0  | >= 0.5.0     | >= 2.4.1      |
-0.32.0        |     2.0      | >= 0.16.2               | >= 0.5.0     | >= 2.4.1      |
-0.34.0        |     2.0      | >= 0.16.2 ... < 1.3.0   | >= 0.5.0     | >= 2.4.1      |
->= 1.0.0      |     2.0      | >= 1.3.0                | >= 0.5.0     | >= 2.4.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.25.2        | 2.0          | >= 0.14.0 ... <= 0.18.0 | <= 0.6.0     | >= 2.4.1      |
+| 0.26.0        | 2.0          | >= 0.16.2 ... <= 1.1.0  | <= 0.6.1     | >= 2.4.1      |
+| 0.27.0        | 2.0          | >= 0.16.2 ... <= 1.1.0  | >= 0.5.0     | >= 2.4.1      |
+| 0.32.0        | 2.0          | >= 0.16.2               | >= 0.5.0     | >= 2.4.1      |
+| 0.34.0        | 2.0          | >= 0.16.2 ... < 1.3.0   | >= 0.5.0     | >= 2.4.1      |
+| >= 1.0.0      | 2.0          | >= 1.3.0                | >= 0.5.0     | >= 2.4.1      |
 
 
 ## Swagger-Spec <a name="swagger-spec"></a>
@@ -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
 
@@ -859,10 +900,11 @@ get '/thing', failure: [
 end
 ```
 
-By adding a `model` key, e.g. this would be taken.
+By adding a `model` key, e.g. this would be taken. Setting an empty string will act like an empty body.
 ```ruby
 get '/thing', failure: [
   { code: 400, message: 'General error' },
+  { code: 403, message: 'Forbidden error', model: '' },
   { code: 422, message: 'Invalid parameter entry', model: Entities::ApiError }
 ] do
   # ...
@@ -1261,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>
 
@@ -1381,6 +1493,94 @@ module API
 end
 ```
 
+#### Inheritance with allOf and discriminator
+```ruby
+module Entities
+  class Pet < Grape::Entity
+    expose :type, documentation: {
+      type: 'string',
+      is_discriminator: true,
+      required: true
+    }
+    expose :name, documentation: {
+      type: 'string',
+      required: true
+    }
+  end
+
+  class Cat < Pet
+    expose :huntingSkill, documentation: {
+      type: 'string',
+      description: 'The measured skill for hunting',
+      default: 'lazy',
+      values: %w[
+        clueless
+        lazy
+        adventurous
+        aggressive
+      ]
+    }
+  end
+end
+```
+
+Should generate this definitions:
+```JSON
+{
+  "definitions": {
+    "Pet": {
+      "type": "object",
+      "discriminator": "petType",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "petType": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "petType"
+      ]
+    },
+    "Cat": {
+      "description": "A representation of a cat",
+      "allOf": [
+        {
+          "$ref": "#/definitions/Pet"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "huntingSkill": {
+              "type": "string",
+              "description": "The measured skill for hunting",
+              "default": "lazy",
+              "enum": [
+                "clueless",
+                "lazy",
+                "adventurous",
+                "aggressive"
+              ]
+            },
+            "petType": {
+              "type": "string",
+              "enum": ["Cat"]
+            }
+          },
+          "required": [
+            "huntingSkill",
+            "petType"
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+
 
 
 ## Securing the Swagger UI <a name="oauth"></a>

data/UPGRADING.md

@@ -1,5 +1,43 @@
 ## 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`.
+
+### Upgrading to >= 1.2.0
+
+- The entity_name class method is now called on parent classes for inherited entities. Now you can do this
+
+```ruby
+module Some::Long::Module
+  class Base < Grape::Entity
+    # ... other shared logic
+    def self.entity_name
+      "V2::#{self.to_s.demodulize}"
+    end
+  end
+
+  def MyEntity < Base
+    # ....
+  end
+
+  def OtherEntity < Base
+    # revert back to the default behavior by hiding the method
+    private_class_method :entity_name
+  end
+end
+```
+
+- Full class name is modified to use `_` separator (e.g. `A_B_C` instead of `A::B::C`).
+
 ### Upgrading to >= 1.1.0
 
 Full class name is used for referencing entity by default (e.g. `A::B::C` instead of just `C`). `Entity` and `Entities` suffixes and prefixes are omitted (e.g. if entity name is `Entities::SomeScope::MyFavourite::Entity` only `SomeScope::MyFavourite` will be used).

data/grape-swagger.gemspec

@@ -7,14 +7,14 @@ 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.add_runtime_dependency 'grape', '~> 1.3.0'
+  s.required_ruby_version = '>= 2.5'
+  s.add_runtime_dependency 'grape', '~> 1.3'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")