grape-swagger 1.4.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d7b364d5b11e9fb35f7c67ce09c2953a7dd50da37cde1bc5b323bbdf9a3b6e4
-  data.tar.gz: 6c825fe6753c899c7f337253495677596acd40320e5e33f83c7c220e71e03e44
+  metadata.gz: 9cff361f819d42d8c3f847c605a31190f82764da573728d043debfe312d30069
+  data.tar.gz: faada4385a0db1fec73606585085deec766991007a9f050df1f2c0bbd9e9e018
 SHA512:
-  metadata.gz: d5e2a5c0d06216c3e2a474051b5986a9f8343a351714b3e255396bbef3984704d85436218fa87e39f0988fbb18b3f5227b2531d514a788f4a4b131028dc19de2
-  data.tar.gz: 6bd210a20332285224d0d24036b9892c729fc84c435991b3e36dd81d8d1976d4ae35c406d3e9d742a82bd90acac75903355c6a827380870e6f1deb2af0b17b7f
+  metadata.gz: 7a86553f29d5b5a338a0ac21d049845ab609ee4adc2864940813f61384a8bcc19c8b0a644bb484f2b79533a111ab16a51c192236b23f540ed672e5e7a161fb23
+  data.tar.gz: 9b5bc29e3ead5f683781cbc0418e3d18f4b056368885e470224bb57ebe03f4232725a971e8589e109240c949aad565e80d5b4ecd31e31f6e5721f0c86c8aaf2f

data/.github/dependabot.yml

@@ -12,3 +12,9 @@ updates:
       day: "friday"
     assignees:
       - "LeFnord"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule: 
+      interval: weekly
+    assignees: 
+     - "LeFnord"

data/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+permissions:
+  contents: read
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+      - name: Run rubocop
+        run: bundle exec rubocop --parallel --format progress
+
+  rspec:
+    runs-on: ubuntu-latest
+    needs: ['rubocop']
+    strategy:
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2', 'head']
+        grape-version: [1.6.2, 1.7.0]
+        model-parser: [grape-swagger-entity, grape-swagger-representable, '']
+    steps:
+    - name: Check out branch
+      uses: actions/checkout@v3
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        GRAPE_VERSION: ${{ matrix.grape-version }}
+        MODEL_PARSER: ${{ matrix.model-parser }}
+        bundler-cache: true
+    - name: Run rspec rest of the suite
+      run: bundle exec rspec

data/.rubocop.yml

@@ -5,7 +5,7 @@ AllCops:
     - vendor/**/*
     - example/**/*
   NewCops: enable
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   SuggestExtensions: false
 
 #  Layout stuff
@@ -101,12 +101,19 @@ Style/HashEachMethods:
 Style/HashLikeCase:
   Enabled: true
 
+Style/HashSyntax:
+  Enabled: false
+
 Style/HashTransformKeys:
   Enabled: true
 
 Style/HashTransformValues:
   Enabled: true
 
+Style/OpenStructUse:
+  Exclude:
+    - spec/**/*
+
 Style/RegexpLiteral:
   Enabled: false
 

data/.rubocop_todo.yml

@@ -1,11 +1,19 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-06-05 12:13:59 +0000 using RuboCop version 0.71.0.
+# on 2022-01-14 10:22:29 UTC using RuboCop version 1.24.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: Include.
+# Include: **/*.gemspec
+Gemspec/RequireMFA:
+  Exclude:
+    - 'grape-swagger.gemspec'
+
 # Offense count: 1
 # Configuration parameters: Include.
 # Include: **/*.gemspec
@@ -13,20 +21,18 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'grape-swagger.gemspec'
 
-# Offense count: 30
+# Offense count: 31
+# Configuration parameters: IgnoredMethods, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 59
-
-# Offense count: 10
-Metrics/CyclomaticComplexity:
-  Max: 13
+  Max: 56
 
-# Offense count: 22
-# Configuration parameters: CountComments, ExcludedMethods.
+# Offense count: 30
+# Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 Metrics/MethodLength:
-  Max: 45
+  Max: 28
 
 # Offense count: 7
+# Configuration parameters: IgnoredMethods.
 Metrics/PerceivedComplexity:
   Max: 16
 
@@ -35,6 +41,20 @@ Style/ClassVars:
   Exclude:
     - 'lib/grape-swagger/doc_methods.rb'
 
-# Offense count: 22
+# Offense count: 23
+# Configuration parameters: AllowedConstants.
 Style/Documentation:
   Enabled: false
+
+# Offense count: 43
+Style/OpenStructUse:
+  Exclude:
+    - 'spec/lib/endpoint_spec.rb'
+    - 'spec/lib/version_spec.rb'
+    - 'spec/support/mock_parser.rb'
+    - 'spec/support/model_parsers/mock_parser.rb'
+    - 'spec/swagger_v2/api_swagger_v2_hide_documentation_path_spec.rb'
+    - 'spec/swagger_v2/api_swagger_v2_mounted_spec.rb'
+    - 'spec/swagger_v2/api_swagger_v2_spec.rb'
+    - 'spec/swagger_v2/errors_spec.rb'
+    - 'spec/swagger_v2/reference_entity_spec.rb'

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-### Next
+### next
 
 #### Features
 
@@ -9,6 +9,46 @@
 * Your contribution here.
 
 
+### 1.6.0 (March 19, 2023)
+
+#### Features
+
+* [#872](https://github.com/ruby-grape/grape-swagger/pull/872): Add `consumes` and `produces` options to `add_swagger_documentation` - [@spaceraccoon](https://github.com/spaceraccoon)
+* [#868](https://github.com/ruby-grape/grape-swagger/pull/868): Add `default` endpoint option to specify default response - [@dhruvCW](https://github.com/dhruvCW)
+
+
+### 1.5.0 (July 28, 2022)
+
+#### Features
+
+* [#862](https://github.com/ruby-grape/grape-swagger/pull/862): Allow using nicknames for body definitions - [@magni-](https://github.com/magni-)
+
+#### Fixes
+
+* [#860](https://github.com/ruby-grape/grape-swagger/pull/860) chore: Included githubactions in the dependabot config [@naveensrinivasan](https://github.com/naveensrinivasan)
+* [#843](https://github.com/ruby-grape/grape-swagger/pull/843) Syntax errors in README.md examples [@remvee](https://github.com/remvee)
+* [#844](https://github.com/ruby-grape/grape-swagger/pull/844) Fixes the regexp used for parsing routes [@senhalil](https://github.com/senhalil)
+* [#847](https://github.com/ruby-grape/grape-swagger/pull/847) Parse route_param type for nested endpoints [@dmoss18](https://github.com/dmoss18)
+* [#856](https://github.com/ruby-grape/grape-swagger/pull/856) Remove unused methods in GrapeSwagger::DocMethods::BuildModelDefinition [@takahashim](https://github.com/takahashim)
+* [#858](https://github.com/ruby-grape/grape-swagger/pull/858): Set permissions for GitHub actions [@naveensrinivasan](https://github.com/naveensrinivasan)
+* [#853](https://github.com/ruby-grape/grape-swagger/pull/853): Add webrick to support Ruby 3.x [@takahashim](https://github.com/takahashim)
+* [#852](https://github.com/ruby-grape/grape-swagger/pull/852): Fix example to work [@takahashim](https://github.com/takahashim)
+* [#846](https://github.com/ruby-grape/grape-swagger/pull/846): Refactor oapi fetch task [@Vachman](https://github.com/Vachman)
+* [#850](https://github.com/ruby-grape/grape-swagger/pull/850): Fix value of enum to be Array [@takahashim](https://github.com/takahashim)
+
+
+### 1.4.3 (January 5, 2022)
+
+#### Fixes
+
+* [#850](https://github.com/ruby-grape/grape-swagger/pull/850): Fix value of `enum` to be `Array` - [@takahashim](https://github.com/takahashim)
+* [#846](https://github.com/ruby-grape/grape-swagger/pull/846): Fixes oapi rake tasks, allows generating sepcs for different API versions.
+* [#852](https://github.com/ruby-grape/grape-swagger/pull/852): Fix example to work without error - [@takahashim](https://github.com/takahashim)
+* [#853](https://github.com/ruby-grape/grape-swagger/pull/853): Add webrick gem so that example works in Ruby 3.x - [@takahashim](https://github.com/takahashim)
+* [#844](https://github.com/ruby-grape/grape-swagger/pull/844): Fixes the regexp used for parsing routes - [@senhalil](https://github.com/senhalil)
+* [#862](https://github.com/ruby-grape/grape-swagger/pull/862): Allow using nicknames for body definitions - [@magni-](https://github.com/magni-)
+* Your contribution here.
+
 ### 1.4.2 (October 22, 2021)
 
 #### Fixes

data/CONTRIBUTING.md

@@ -115,7 +115,7 @@ git push origin my-feature-branch -f
 
 ## Check on Your Pull Request
 
-Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+Go back to your pull request after a few minutes and see whether it passed muster with GitHub Actions. Everything should look green, otherwise fix issues and amend your commit as described above.
 
 ## Be Patient
 

data/Gemfile

@@ -2,18 +2,16 @@
 
 source 'http://rubygems.org'
 
-ruby RUBY_VERSION
-
 gemspec
 
-gem 'grape', case version = ENV['GRAPE_VERSION'] || '>= 1.5.0'
+gem 'grape', case version = ENV.fetch('GRAPE_VERSION', '~> 1.7')
              when 'HEAD'
                { git: 'https://github.com/ruby-grape/grape' }
              else
                version
              end
 
-gem ENV['MODEL_PARSER'] if ENV.key?('MODEL_PARSER')
+gem ENV.fetch('MODEL_PARSER', nil) if ENV.key?('MODEL_PARSER')
 
 group :development, :test do
   gem 'bundler'
@@ -21,13 +19,14 @@ group :development, :test do
   gem 'pry', platforms: [:mri]
   gem 'pry-byebug', platforms: [:mri]
 
-  gem 'rack', '~> 2.2'
+  gem 'rack', '~> 3.0'
   gem 'rack-cors'
   gem 'rack-test'
   gem 'rake'
   gem 'rdoc'
   gem 'rspec', '~> 3.9'
   gem 'rubocop', '~> 1.0', require: false
+  gem 'webrick'
 end
 
 group :test do
@@ -35,7 +34,9 @@ group :test do
 
   gem 'ruby-grape-danger', '~> 0.2.0', require: false
   gem 'simplecov', require: false
+end
 
+group :test, :development do
   unless ENV['MODEL_PARSER'] == 'grape-swagger-entity'
     gem 'grape-swagger-entity', git: 'https://github.com/ruby-grape/grape-swagger-entity'
   end

data/README.md

@@ -206,6 +206,8 @@ end
 * [array_use_braces](#array_use_braces)
 * [api_documentation](#api_documentation)
 * [specific_api_documentation](#specific_api_documentation)
+* [consumes](#consumes)
+* [produces](#produces)
 
 You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
 The examples show the default value.
@@ -432,6 +434,24 @@ add_swagger_documentation \
    specific_api_documentation: { desc: 'Reticulated splines API swagger-compatible endpoint documentation.' }
 ```
 
+#### consumes
+
+Customize the Swagger API default global `consumes` field value.
+
+```ruby
+add_swagger_documentation \
+   consumes: ['application/json', 'application/x-www-form-urlencoded']
+```
+
+#### produces
+
+Customize the Swagger API default global `produces` field value.
+
+```ruby
+add_swagger_documentation \
+   produces: ['text/plain']
+```
+
 ## Routes Configuration <a name="routes"></a>
 
 * [Swagger Header Parameters](#headers)
@@ -817,7 +837,7 @@ The example parameter will populate the Swagger UI with the example value, and c
 ```ruby
 params do
   requires :id, type: Integer, documentation: { example: 123 }
-  optional :name, type String, documentation: { example: 'Buddy Guy' }
+  optional :name, type: String, documentation: { example: 'Buddy Guy' }
 end
 ```
 
@@ -843,7 +863,7 @@ namespace 'store/order', desc: 'Order operations within a store', swagger: { nes
   get :order_id do
   	...
   end
-  namespace 'actions', desc: 'Order actions' do, nested: false
+  namespace 'actions', desc: 'Order actions', nested: false do
     get 'evaluate' do
       ...
     end
@@ -1022,6 +1042,50 @@ end
 }
 ```
 
+#### Default response <a name="default-response"></a>
+
+By setting the `default` option you can also define a default response that is the result returned for all unspecified status codes.
+The definition supports the same syntax as `success` or `failure`.
+
+In the following cases, the schema ref would be taken from route.
+
+```ruby
+desc 'thing', default: { message: 'the default response' }
+get '/thing' do
+  # ...
+end
+```
+The generated swagger section will be something like
+
+```json
+"responses": {
+  "default": {
+    "description": "the default response"
+  }
+},
+```
+Just like with `success` or `failure` you can also provide a `model` parameter.
+
+```ruby
+desc 'Get a list of stuff',
+    default: { model: Entities::UseResponse, message: 'the default response' }
+get do
+  # your code comes here
+end
+```
+The generated swagger document will then correctly reference the model schema.
+
+```json
+"responses": {
+  "default": {
+    "description": "the default response",
+    "schema": {
+      "$ref": "#/definitions/UseResponse"
+    }
+  }
+},
+```
+
 
 #### Extensions <a name="extensions"></a>
 
@@ -1265,7 +1329,7 @@ end
 
 The result will look like following:
 
-```
+```json
   "responses": {
     "200": {
       "description": "Get a kitten",
@@ -1292,7 +1356,7 @@ end
 
 The result will look like following:
 
-```
+```json
   "responses": {
     "200": {
       "description": "Get kittens",
@@ -1319,7 +1383,7 @@ get '/things' do
 end
 ```
 The result will look like following:
-```
+```json
   "responses": {
     "200": {
       "description": "Multiple response",
@@ -1351,7 +1415,7 @@ get '/things' do
 end
 ```
 The result will look like following:
-```
+```json
   "responses": {
     "200": {
       "description": "Multiple response with array",
@@ -1525,7 +1589,7 @@ end
 ```
 
 Should generate this definitions:
-```JSON
+```json
 {
   "definitions": {
     "Pet": {
@@ -1718,9 +1782,10 @@ GrapeSwagger::Rake::OapiTasks.new('::Api::Base')
 ```
 rake oapi:fetch
 params:
-- store={ true | file_name } – save as JSON (optional)
+- store={ true | file_name.json } – save as JSON (optional)
 - resource=resource_name     – get only for this one (optional)
 ```
+For mutliversion API it creates several files with following naming: file_name_`API_VERSION`.json      
 
 #### OpenApi/Swagger Validation
 

data/UPGRADING.md

@@ -1,8 +1,19 @@
 ## Upgrading Grape-swagger
 
+### Upgrading to >= 1.5.0
+
+- The names generated for body parameter definitions and their references has changed. It'll now include the HTTP action as well as any path parameters.
+  - E.g, given a `PUT /things/:id` endpoint, `paths.things/{id}.put.parameters` in the generated Swaggerfile will contain the following:
+  - With `grape-swagger < 1.5.0`: `{ "name": "Things", ..., "schema": { "$ref": "#/definitions/putThings" } }`
+  - With `grape-swagger >= 1.5.0`: `{ "name": "putThingsId", ..., "schema": { "$ref": "#/definitions/putThingsId" } }`
+- If you use the `nickname` option for an endpoint, that nickname will be used for both the parameter name and its definition reference.
+  - E.g., if the endpoint above were nicknamed `put-thing`, the generated Swaggerfile will contain `{ "name": "put-thing", ..., "schema": { "$ref": "#/definitions/put-thing" } }`
+
+
 ### 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`.
+- The value of the `enum` attribute is now always an Array. If it has only one value, it will be a one-element Array.
 
 ### Upgrading to >= 1.4.0
 

data/example/config.ru

@@ -1,4 +1,5 @@
-require 'rack/cors'
+Bundler.require ENV['RACK_ENV']
+
 use Rack::Cors do
   allow do
     origins '*'
@@ -12,7 +13,6 @@ require './api/endpoints'
 require './api/entities'
 
 class Base < Grape::API
-  require 'grape-entity'
   require '../lib/grape-swagger'
   format :json
 

data/grape-swagger.gemspec

@@ -13,10 +13,11 @@ Gem::Specification.new do |s|
   s.summary     = 'Add auto generated documentation to your Grape API that can be displayed with Swagger.'
   s.license     = 'MIT'
 
-  s.required_ruby_version = '>= 2.5'
+  s.metadata['rubygems_mfa_required'] = 'true'
+
+  s.required_ruby_version = '>= 2.7'
   s.add_runtime_dependency 'grape', '~> 1.3'
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")
   s.require_paths = ['lib']
 end

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

@@ -4,14 +4,9 @@ module GrapeSwagger
   module DocMethods
     class BuildModelDefinition
       class << self
-        def build(model, properties, required, other_def_properties = {})
+        def build(_model, properties, required, other_def_properties = {})
           definition = { type: 'object', properties: properties }.merge(other_def_properties)
 
-          if required.nil?
-            required_attrs = required_attributes(model)
-            definition[:required] = required_attrs unless required_attrs.blank?
-          end
-
           definition[:required] = required if required.is_a?(Array) && required.any?
 
           definition
@@ -67,20 +62,6 @@ module GrapeSwagger
             end
           end
         end
-
-        private
-
-        def required_attributes(model)
-          parse_entity(model) || parse_representable(model)
-        end
-
-        def parse_entity(model)
-          return unless model.respond_to?(:documentation)
-        end
-
-        def parse_representable(model)
-          return unless model.respond_to?(:map)
-        end
       end
     end
   end

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

@@ -38,15 +38,15 @@ module GrapeSwagger
         end
 
         def parent_definition_of_params(params, path, route)
-          definition_name = OperationId.manipulate(parse_model(path))
-          referenced_definition = build_definition(definition_name, params, route.request_method.downcase)
-          definition = @definitions[referenced_definition]
+          definition_name = OperationId.build(route, path)
+          build_definition(definition_name, params)
+          definition = @definitions[definition_name]
 
           move_params_to_new(definition, params)
 
           definition[:description] = route.description if route.try(:description)
 
-          build_body_parameter(referenced_definition, definition_name, route.options)
+          build_body_parameter(definition_name, route.options)
         end
 
         def move_params_to_new(definition, params)
@@ -142,17 +142,16 @@ module GrapeSwagger
           definition[:required].push(*value)
         end
 
-        def build_body_parameter(reference, name, options)
+        def build_body_parameter(name, options)
           {}.tap do |x|
             x[:name] = options[:body_name] || name
             x[:in] = 'body'
             x[:required] = true
-            x[:schema] = { '$ref' => "#/definitions/#{reference}" }
+            x[:schema] = { '$ref' => "#/definitions/#{name}" }
           end
         end
 
-        def build_definition(name, params, verb = nil)
-          name = "#{verb}#{name}" if verb
+        def build_definition(name, params)
           @definitions[name] = should_expose_as_array?(params) ? array_type : object_type
 
           name

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

@@ -163,8 +163,10 @@ module GrapeSwagger
             parse_enum_or_range_values(values.call) if values.parameters.empty?
           when Range
             parse_range_values(values) if values.first.is_a?(Integer)
+          when Array
+            { enum: values }
           else
-            { enum: values } if values
+            { enum: [values] } if values
           end
         end