grape-swagger 1.2.1 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ced0e59624b64b14e517815c13c6761c970da13cfd7e6d5c82493b1bb49c815
-  data.tar.gz: a5891f3a10dc5e3ae96bb1f295dcf1978f0758175160b1681ba5f85f0b7cc206
+  metadata.gz: 2bc71f9cae392ed1e1fcb574570c75d800d99120c98ad9061b263edf80dc997d
+  data.tar.gz: f2cf0bca726860789875007043edb8ce689e7e779eb3273b1f376cb5b161949f
 SHA512:
-  metadata.gz: 61c9297050672b095bf2ab8a6648420b6226fa5ecaa2b1b2df07e99c271dba4f1fe9547a77eae5dc4e1b5d0b29035f823e389957b57149f4fb79cf3187597ee9
-  data.tar.gz: 55f926c09f83bfe6e0ab15caeac329acf6f6d623d9c579b89c872fdd2f11f5ddece4e0a74259f921688bcf8e2255fecd908fce3f2eb4b2b58ed449803d3c2900
+  metadata.gz: 6e6beba3aaba4f3fa5fc152127ad84c5dcae6c44bffecf276ae778e9ce779eba2a90feb40a7110afaffff1afc4ab0af7d2128fddf993ea304621e2a9428e2435
+  data.tar.gz: 3190175c602571c28e1cb2678b7c94ce0ac4f663cc163d6dd03c03a0e3fee5b75a80e3ff3a3e3f6e0eb964727cccd5dc7914db32dee98901e2000c0ebd2d33a8

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,32 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  rspec:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0']
+        grape-version: [1.5.3, 1.4.0, 1.3.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
+    - name: Run rubocop
+      run: bundle exec rubocop

data/.rubocop.yml

@@ -4,7 +4,9 @@ AllCops:
   Exclude:
     - vendor/**/*
     - example/**/*
-  TargetRubyVersion: 2.7
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
 
 #  Layout stuff
 #
@@ -27,6 +29,10 @@ Layout/SpaceAroundMethodCallOperator:
 
 # Lint stuff
 #
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/**/*
+
 Lint/DeprecatedOpenSSLConstant:
   Enabled: true
 
@@ -49,7 +55,7 @@ Metrics/BlockLength:
     - spec/**/*
 
 Metrics/ClassLength:
-  Max: 300
+  Max: 350
 
 Metrics/CyclomaticComplexity:
   Max: 17
@@ -68,6 +74,9 @@ Naming:
 Style/AccessorGrouping:
   Enabled: true
 
+Style/AsciiComments:
+  Enabled: false
+
 Style/ArrayCoercion:
   Enabled: true
 
@@ -80,8 +89,12 @@ Style/CaseLikeIf:
 Style/ExponentialNotation:
   Enabled: true
 
+Style/ExplicitBlockArgument:
+  Enabled: false
+
 Style/HashAsLastArrayItem:
   Enabled: true
+
 Style/HashEachMethods:
   Enabled: true
 
@@ -114,5 +127,3 @@ Style/RedundantRegexpEscape:
 
 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,43 @@
 * Your contribution here.
 
 
+### 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

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,7 +27,7 @@ group :development, :test do
   gem 'rake'
   gem 'rdoc'
   gem 'rspec', '~> 3.9'
-  gem 'rubocop', '~> 0.88', require: false
+  gem 'rubocop', '~> 1.0', require: false
 end
 
 group :test do

data/README.md

@@ -451,6 +451,7 @@ add_swagger_documentation \
 * [Collection Format](#collection-format)
 * [Hiding parameters](#hiding-parameters)
 * [Setting a Swagger default value](#default-value)
+* [Example parameter value](#param-example)
 * [Response documentation](#response)
 * [Changing default status codes](#change-status)
 * [File response](#file-response)
@@ -458,6 +459,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 +770,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 +779,16 @@ params do
 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 +869,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 +1272,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.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

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
@@ -30,7 +30,7 @@ module GrapeSwagger
 
         def add_braces(parameter, related_parameters)
           param_name = parameter[:name].gsub(/\A(.*)\[\]\z/, '\1')
-          related_parameters.each { |p| p[:name] = p[:name].gsub(param_name, param_name + '[]') }
+          related_parameters.each { |p| p[:name] = p[:name].gsub(param_name, "#{param_name}[]") }
         end
 
         def add_array(parameter, related_parameters)

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

@@ -181,7 +181,7 @@ 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 additionalProperties example]
         end
 
         def deletable?(param)

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

@@ -27,6 +27,7 @@ module GrapeSwagger
           document_required(settings)
           document_additional_properties(settings)
           document_add_extensions(settings)
+          document_example(settings)
 
           @parsed_param
         end
@@ -112,6 +113,11 @@ module GrapeSwagger
           @parsed_param[:additionalProperties] = additional_properties if additional_properties
         end
 
+        def document_example(settings)
+          example = settings[:example]
+          @parsed_param[:example] = example if example
+        end
+
         def param_type(value_type)
           param_type = value_type[:param_type] || value_type[:in]
           if value_type[:path].include?("{#{value_type[:param_name]}}")

data/lib/grape-swagger/doc_methods.rb

@@ -17,6 +17,61 @@ require 'grape-swagger/doc_methods/version'
 
 module GrapeSwagger
   module DocMethods
+    DEFAULTS =
+      {
+        info: {},
+        models: [],
+        doc_version: '0.0.1',
+        target_class: nil,
+        mount_path: '/swagger_doc',
+        host: nil,
+        base_path: nil,
+        add_base_path: false,
+        add_version: true,
+        add_root: false,
+        hide_documentation_path: true,
+        format: :json,
+        authorizations: nil,
+        security_definitions: nil,
+        security: nil,
+        api_documentation: { desc: 'Swagger compatible API description' },
+        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
+        endpoint_auth_wrapper: nil,
+        swagger_endpoint_guard: nil,
+        token_owner: nil
+      }.freeze
+
+    FORMATTER_METHOD = %i[format default_format default_error_formatter].freeze
+
+    def self.output_path_definitions(combi_routes, endpoint, target_class, options)
+      output = endpoint.swagger_object(
+        target_class,
+        endpoint.request,
+        options
+      )
+
+      paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
+      tags                 = tags_from(paths, options)
+
+      output[:tags]        = tags unless tags.empty? || paths.blank?
+      output[:paths]       = paths unless paths.blank?
+      output[:definitions] = definitions unless definitions.blank?
+
+      output
+    end
+
+    def self.tags_from(paths, options)
+      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+
+      if options[:tags]
+        names = options[:tags].map { |t| t[:name] }
+        tags.reject! { |t| names.include?(t[:name]) }
+        tags += options[:tags]
+      end
+
+      tags
+    end
+
     def hide_documentation_path
       @@hide_documentation_path
     end
@@ -26,54 +81,32 @@ module GrapeSwagger
     end
 
     def setup(options)
-      options = defaults.merge(options)
+      options = DEFAULTS.merge(options)
 
       # options could be set on #add_swagger_documentation call,
       # for available options see #defaults
       target_class     = options[:target_class]
       guard            = options[:swagger_endpoint_guard]
-      formatter        = options[:format]
       api_doc          = options[:api_documentation].dup
       specific_api_doc = options[:specific_api_documentation].dup
 
       class_variables_from(options)
 
-      if formatter
-        %i[format default_format default_error_formatter].each do |method|
-          send(method, formatter)
-        end
-      end
+      setup_formatter(options[:format])
 
       desc api_doc.delete(:desc), api_doc
 
-      output_path_definitions = proc do |combi_routes, endpoint|
-        output = endpoint.swagger_object(
-          target_class,
-          endpoint.request,
-          options
-        )
-
-        paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
-        tags                 = tags_from(paths, options)
-
-        output[:tags]        = tags unless tags.empty? || paths.blank?
-        output[:paths]       = paths unless paths.blank?
-        output[:definitions] = definitions unless definitions.blank?
-
-        output
-      end
-
       instance_eval(guard) unless guard.nil?
 
       get mount_path do
         header['Access-Control-Allow-Origin']   = '*'
         header['Access-Control-Request-Method'] = '*'
 
-        output_path_definitions.call(target_class.combined_namespace_routes, self)
+        GrapeSwagger::DocMethods
+          .output_path_definitions(target_class.combined_namespace_routes, self, target_class, options)
       end
 
-      desc specific_api_doc.delete(:desc), { params:
-        specific_api_doc.delete(:params) || {} }.merge(specific_api_doc)
+      desc specific_api_doc.delete(:desc), { params: specific_api_doc.delete(:params) || {}, **specific_api_doc }
 
       params do
         requires :name, type: String, desc: 'Resource name of mounted API'
@@ -88,51 +121,21 @@ module GrapeSwagger
         combined_routes = target_class.combined_namespace_routes[params[:name]]
         error!({ error: 'named resource not exist' }, 400) if combined_routes.nil?
 
-        output_path_definitions.call({ params[:name] => combined_routes }, self)
+        GrapeSwagger::DocMethods
+          .output_path_definitions({ params[:name] => combined_routes }, self, target_class, options)
       end
     end
 
-    def defaults
-      {
-        info: {},
-        models: [],
-        doc_version: '0.0.1',
-        target_class: nil,
-        mount_path: '/swagger_doc',
-        host: nil,
-        base_path: nil,
-        add_base_path: false,
-        add_version: true,
-        add_root: false,
-        hide_documentation_path: true,
-        format: :json,
-        authorizations: nil,
-        security_definitions: nil,
-        security: nil,
-        api_documentation: { desc: 'Swagger compatible API description' },
-        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
-        endpoint_auth_wrapper: nil,
-        swagger_endpoint_guard: nil,
-        token_owner: nil
-      }
-    end
-
     def class_variables_from(options)
       @@mount_path              = options[:mount_path]
       @@class_name              = options[:class_name] || options[:mount_path].delete('/')
       @@hide_documentation_path = options[:hide_documentation_path]
     end
 
-    def tags_from(paths, options)
-      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+    def setup_formatter(formatter)
+      return unless formatter
 
-      if options[:tags]
-        names = options[:tags].map { |t| t[:name] }
-        tags.reject! { |t| names.include?(t[:name]) }
-        tags += options[:tags]
-      end
-
-      tags
+      FORMATTER_METHOD.each { |method| send(method, formatter) }
     end
   end
 end