grape-swagger 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fd414192a99ad92ea5ebdc015373059ab02819a7512119897a6fa71f309c083
-  data.tar.gz: 8ed9bd4a2fcb9d8e07b86aa899bf5ca7da74d716c8e45bf90667741abeedb718
+  metadata.gz: 329bb3676657055c5c086902b97ce065a4b7886d9de5ea5542e7874052ab92a9
+  data.tar.gz: 4290d2ea021d4cca08b5ba4a83033fa9df8476b79cc500d9d0de9476e1190f6a
 SHA512:
-  metadata.gz: 7abb761a0965db3a41dca82d2a72a451f95c2e5a13cfaaede2603c8312cb9077499ca446e1b551f308ecb293a8c2b3c8c1fad7aa378e674457848e817b84e934
-  data.tar.gz: f284e5a252115e1b0d673ec07ec4b2ace2371b001cdf62e4d9e48331e0f115547ec2ee659ccba2a2d1fdc7f868c1c0ecfb1f5c341e84f1f6f7369782a4eb4f58
+  metadata.gz: abe0988e09f9fd987983977df65419230c04c60ef89ebb135921cf528c61c05e196873d3077db99b7540e94453929bc987e873c39f39f98adf70f77816f4fd75
+  data.tar.gz: 9530e8d9f2c2540ec167c8cbfe7a2a7775f9067ddadcca51fe7d32abee03d23a537970b4a1703b202a4d7d9c61b941fb8cb183817e9743d291e15c4c6d0db69e

data/.rubocop.yml

@@ -16,6 +16,9 @@ Metrics/BlockLength:
   Exclude:
     - spec/**/*
 
+Metrics/ClassLength:
+  Max: 300
+
 Metrics/LineLength:
   Max: 120
   Exclude:

data/CHANGELOG.md

@@ -8,6 +8,17 @@
 
 * Your contribution here.
 
+###  0.30.0 (July 19, 2018)
+
+#### Features
+
+* [#684](https://github.com/ruby-grape/grape-swagger/pull/684): Add response headers - [@jdmurphy](https://github.com/jdmurphy).
+
+#### Fixes
+
+* [#681](https://github.com/ruby-grape/grape-swagger/pull/681): Provide error schemas when an endpoint can return a 204 - [@adstratm](https://github.com/adstratm).
+* [#683](https://github.com/ruby-grape/grape-swagger/pull/683): Fix handling of arrays of complex entities in params so that valid OpenAPI spec is generated - [@jdmurphy](https://github.com/jdmurphy).
+
 ###  0.29.0 (May 22, 2018)
 
 #### Features

data/Gemfile

@@ -26,11 +26,11 @@ group :development, :test do
   gem 'rake'
   gem 'rdoc'
   gem 'rspec', '~> 3.0'
-  gem 'rubocop', '~>0.51', require: false
+  gem 'rubocop', '~> 0.58', require: false
 end
 
 group :test do
-  gem 'coveralls', require: false
+  gem 'coveralls', '~> 0.8', require: false
   gem 'grape-swagger-entity'
   gem 'ruby-grape-danger', '~> 0.1.1', require: false
   gem 'simplecov', require: false

data/README.md

@@ -17,7 +17,7 @@
 * [Routes Configuration](#routes)
 * [Using Grape Entities](#grape-entity)
 * [Securing the Swagger UI](#oauth)
-* [Examples](#examples)
+* [Example](#example)
 * [Rake Tasks](#rake)
 
 
@@ -398,6 +398,7 @@ A hash merged into the `info` key of the JSON documentation.
 * [File response](#file-response)
 * [Extensions](#extensions)
 * [Response examples documentation](#response-examples)
+* [Response headers documentation](#response-headers)
 
 #### Swagger Header Parameters  <a name="headers" />
 
@@ -1037,6 +1038,60 @@ The result will look like following:
 
 Failure information can be passed as an array of arrays or an array of hashes.
 
+#### Response headers documentation <a name="response-headers" />
+
+You can also add header information to your responses by using the `desc` DSL with block syntax.
+
+By specifying headers to `success` and `failure`.
+
+```ruby
+desc 'This returns headers' do
+  success model: Thing, headers: { 'Location' => { description: 'Location of resource', type: 'string' } }
+  failure [[404, 'NotFound', ApiError, { 'application/json' => { code: 404, message: 'Not found' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
+end
+get '/thing' do
+  ...
+end
+```
+
+The result will look like following:
+
+```json
+  "responses": {
+    "200": {
+      "description": "This returns examples",
+      "schema": {
+        "$ref": "#/definitions/Thing"
+      },
+      "headers": {
+        "Location": {
+          "description": "Location of resource",
+          "type": "string"
+        }
+      }
+    },
+    "404": {
+      "description": "NotFound",
+      "schema": {
+        "$ref": "#/definitions/ApiError"
+      },
+      "examples": {
+        "application/json": {
+          "code": 404,
+          "message": "Not found"
+        }
+      },
+      "headers": {
+        "Date": {
+          "description": "Date of failure",
+          "type": "string"
+        }
+      }
+    }
+  }
+```
+
+Failure information can be passed as an array of arrays or an array of hashes.
 
 ## Using Grape Entities <a name="grape-entity" />
 
@@ -1229,7 +1284,7 @@ role - only admins can see this endpoint.
 
 
 
-## Examples <a="example" />
+## Example <a name="example" />
 
 Go into example directory and run it: `$ bundle exec rackup`
 go to: `http://localhost:9292/swagger_doc` to get it

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

@@ -177,9 +177,16 @@ module GrapeSwagger
         def prepare_nested_types(params)
           params.each do |param|
             next unless param[:items]
-            param[:type] = param[:items][:type] == 'array' ? 'string' : param[:items][:type]
+
+            param[:type] = if param[:items][:type] == 'array'
+                             'string'
+                           elsif param[:items].key?('$ref')
+                             param[:type] = 'object'
+                           else
+                             param[:items][:type]
+                           end
             param[:format] = param[:items][:format] if param[:items][:format]
-            param.delete(:items)
+            param.delete(:items) if param[:type] != 'object'
           end
         end
 

data/lib/grape-swagger/endpoint.rb

@@ -195,7 +195,7 @@ module Grape
 
     def response_object(route)
       codes = http_codes_from_route(route)
-      codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3] } : x }
+      codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3], headers: x[4] } : x }
 
       codes.each_with_object({}) do |value, memo|
         value[:message] ||= ''
@@ -210,13 +210,14 @@ module Grape
           value[:code] = 204
         end
 
-        next if memo.key?(204)
+        next if value[:code] == 204
         next unless !response_model.start_with?('Swagger_doc') && (@definitions[response_model] || value[:model])
 
         @definitions[response_model][:description] = description_object(route)
 
         memo[value[:code]][:schema] = build_reference(route, value, response_model)
         memo[value[:code]][:examples] = value[:examples] if value[:examples]
+        memo[value[:code]][:headers] = value[:headers] if value[:headers]
       end
     end
 
@@ -240,6 +241,7 @@ module Grape
         default_code[:model] = @entity[:model] if @entity[:model].present?
         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]
       else
         default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
         default_code[:model] = @entity if @entity

data/lib/grape-swagger/version.rb

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

data/spec/issues/680_keep_204_error_schemas_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'when the main endpoint response is a 204 all error schemas are lost' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_680 do
+        desc 'delete something',
+             is_array: true,
+             success: { status: 204 },
+             failure: [
+               [401, 'Unauthorized', Entities::ApiError],
+               [403, 'Forbidden', Entities::ApiError],
+               [404, 'Not Found', Entities::ApiError]
+             ]
+
+        delete do
+          status 204
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  context 'when an endpoint can return a 204' do
+    let(:responses) { subject['paths']['/issue_680']['delete']['responses'] }
+
+    it 'returns the description but not a schema for a 204 response' do
+      expect(responses['204']['description']).to eq('delete something')
+      expect(responses['204']['schema']).to be_nil
+    end
+
+    it 'returns a description AND a schema for a 401 response' do
+      expect(responses['401']['description']).to eq('Unauthorized')
+      expect(responses['401']['schema']).to_not be_nil
+    end
+
+    it 'returns a description AND a schema for a 403 response' do
+      expect(responses['403']['description']).to eq('Forbidden')
+      expect(responses['403']['schema']).to_not be_nil
+    end
+
+    it 'returns a description AND a schema for a 404 response' do
+      expect(responses['404']['description']).to eq('Not Found')
+      expect(responses['404']['schema']).to_not be_nil
+    end
+  end
+end

data/spec/lib/move_params_spec.rb

@@ -325,5 +325,193 @@ describe GrapeSwagger::DocMethods::MoveParams do
         it { expect(params).to eql expected_params }
       end
     end
+
+    describe 'prepare_nested_types' do
+      before :each do
+        subject.send(:prepare_nested_types, params)
+      end
+
+      let(:params) do
+        [
+          {
+            in: 'body',
+            name: 'address[street_lines]',
+            description: 'street lines',
+            type: 'array',
+            items: {
+              type: 'string'
+            },
+            required: true
+          }
+        ]
+      end
+
+      context 'when params contains nothing with :items key' do
+        let(:params) do
+          [
+            {
+              in: 'body',
+              name: 'phone_number',
+              description: 'phone number',
+              type: 'string',
+              required: true
+            }
+          ]
+        end
+
+        let(:expected_params) do
+          [
+            {
+              in: 'body',
+              name: 'phone_number',
+              description: 'phone number',
+              type: 'string',
+              required: true
+            }
+          ]
+        end
+
+        it 'does nothing' do
+          expect(params).to eq expected_params
+        end
+      end
+
+      context 'when params contains :items key with array type' do
+        let(:params) do
+          [
+            {
+              in: 'body',
+              name: 'address_street_lines',
+              description: 'street lines',
+              type: 'array',
+              items: {
+                type: 'array'
+              },
+              required: true
+            }
+          ]
+        end
+
+        let(:expected_params) do
+          [
+            {
+              in: 'body',
+              name: 'address_street_lines',
+              description: 'street lines',
+              type: 'string',
+              required: true
+            }
+          ]
+        end
+
+        it 'sets type to string and removes :items' do
+          expect(params).to eq expected_params
+        end
+      end
+
+      context 'when params contains :items key with $ref' do
+        let(:params) do
+          [
+            {
+              in: 'body',
+              name: 'address_street_lines',
+              description: 'street lines',
+              type: 'array',
+              items: {
+                '$ref' => '#/definitions/StreetLine'
+              },
+              required: true
+            }
+          ]
+        end
+
+        let(:expected_params) do
+          [
+            {
+              in: 'body',
+              name: 'address_street_lines',
+              description: 'street lines',
+              type: 'object',
+              items: {
+                '$ref' => '#/definitions/StreetLine'
+              },
+              required: true
+            }
+          ]
+        end
+
+        it 'sets type to object and does not remove :items' do
+          expect(params).to eq expected_params
+        end
+      end
+
+      context 'when params contains :items without $ref or array type' do
+        let(:params) do
+          [
+            {
+              in: 'body',
+              name: 'address_street_lines',
+              description: 'street lines',
+              type: 'array',
+              items: {
+                type: 'string'
+              },
+              required: true
+            }
+          ]
+        end
+
+        let(:expected_params) do
+          [
+            {
+              in: 'body',
+              name: 'address_street_lines',
+              description: 'street lines',
+              type: 'string',
+              required: true
+            }
+          ]
+        end
+
+        it 'sets type to :items :type and removes :items' do
+          expect(params).to eq expected_params
+        end
+      end
+
+      context 'when params contains :items key with :format' do
+        let(:params) do
+          [
+            {
+              in: 'body',
+              name: 'street_number',
+              description: 'street number',
+              type: 'array',
+              items: {
+                type: 'integer',
+                format: 'int32'
+              },
+              required: true
+            }
+          ]
+        end
+
+        let(:expected_params) do
+          [
+            {
+              in: 'body',
+              name: 'street_number',
+              description: 'street number',
+              type: 'integer',
+              format: 'int32',
+              required: true
+            }
+          ]
+        end
+
+        it 'sets format and removes :items' do
+          expect(params).to eq expected_params
+        end
+      end
+    end
   end
 end

data/spec/spec_helper.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
-require 'simplecov'
-require 'coveralls'
-
-SimpleCov.formatter = Coveralls::SimpleCov::Formatter
-SimpleCov.start do
-  add_filter 'spec/'
-  add_filter 'example/'
+if RUBY_ENGINE == 'ruby'
+  require 'simplecov'
+  require 'coveralls'
+
+  SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+  SimpleCov.start do
+    add_filter 'spec/'
+    add_filter 'example/'
+  end
+  Coveralls.wear!
 end
-Coveralls.wear!
 
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 

data/spec/swagger_v2/api_swagger_v2_response_with_headers_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response with headers' do
+  # include_context "#{MODEL_PARSER} swagger header"
+
+  before :all do
+    module TheApi
+      class ResponseApiHeaders < Grape::API
+        format :json
+
+        desc 'This returns headers' do
+          success model: Entities::UseResponse, headers: { 'Location' => { description: 'Location of resource', type: 'string' } }
+          failure [[404, 'NotFound', Entities::ApiError, { 'application/json' => { code: 404, message: 'Not found' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
+        end
+        get '/response_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This syntax also returns headers' do
+          success model: Entities::UseResponse, headers: { 'Location' => { description: 'Location of resource', type: 'string' } }
+          failure [
+            {
+              code: 404,
+              message: 'NotFound',
+              model: Entities::ApiError,
+              headers: { 'Date' => { description: 'Date of failure', type: 'string' } }
+            },
+            {
+              code: 400,
+              message: 'BadRequest',
+              model: Entities::ApiError,
+              headers: { 'Date' => { description: 'Date of failure', type: 'string' } }
+            }
+          ]
+        end
+        get '/response_failure_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This does not return headers' do
+          success model: Entities::UseResponse
+          failure [[404, 'NotFound', Entities::ApiError]]
+        end
+        get '/response_no_headers' do
+          { 'declared_params' => declared(params) }
+        end
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiHeaders
+  end
+
+  describe 'response headers' do
+    let(:header_200) do
+      { 'Location' => { 'description' => 'Location of resource', 'type' => 'string' } }
+    end
+    let(:header_404) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+    let(:examples_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_headers']['get']).to eql(
+        'description' => 'This returns headers',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns headers', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'headers' => header_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => examples_404, 'headers' => header_404 }
+        },
+        'tags' => ['response_headers'],
+        'operationId' => 'getResponseHeaders'
+      )
+    end
+  end
+
+  describe 'response failure headers' do
+    let(:header_200) do
+      { 'Location' => { 'description' => 'Location of resource', 'type' => 'string' } }
+    end
+    let(:header_404) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+    let(:header_400) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_failure_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_failure_headers']['get']).to eql(
+        'description' => 'This syntax also returns headers',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This syntax also returns headers', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'headers' => header_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'headers' => header_404 },
+          '400' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'headers' => header_400 }
+        },
+        'tags' => ['response_failure_headers'],
+        'operationId' => 'getResponseFailureHeaders'
+      )
+    end
+  end
+
+  describe 'response no headers' do
+    subject do
+      get '/swagger_doc/response_no_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_no_headers']['get']).to eql(
+        'description' => 'This does not return headers',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This does not return headers', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['response_no_headers'],
+        'operationId' => 'getResponseNoHeaders'
+      )
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Tim Vandecasteele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-22 00:00:00.000000000 Z
+date: 2018-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -32,7 +32,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".coveralls.yml"
-- ".document"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -91,6 +90,7 @@ files:
 - spec/issues/587_range_parameter_delimited_by_dash_spec.rb
 - spec/issues/605_root_route_documentation_spec.rb
 - spec/issues/650_params_array_spec.rb
+- spec/issues/680_keep_204_error_schemas_spec.rb
 - spec/lib/data_type_spec.rb
 - spec/lib/endpoint_spec.rb
 - spec/lib/extensions_spec.rb
@@ -131,6 +131,7 @@ files:
 - spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb
 - spec/swagger_v2/api_swagger_v2_response_spec.rb
 - spec/swagger_v2/api_swagger_v2_response_with_examples_spec.rb
+- spec/swagger_v2/api_swagger_v2_response_with_headers_spec.rb
 - spec/swagger_v2/api_swagger_v2_spec.rb
 - spec/swagger_v2/api_swagger_v2_status_codes_spec.rb
 - spec/swagger_v2/api_swagger_v2_type-format_spec.rb
@@ -207,6 +208,7 @@ test_files:
 - spec/issues/587_range_parameter_delimited_by_dash_spec.rb
 - spec/issues/605_root_route_documentation_spec.rb
 - spec/issues/650_params_array_spec.rb
+- spec/issues/680_keep_204_error_schemas_spec.rb
 - spec/lib/data_type_spec.rb
 - spec/lib/endpoint_spec.rb
 - spec/lib/extensions_spec.rb
@@ -247,6 +249,7 @@ test_files:
 - spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb
 - spec/swagger_v2/api_swagger_v2_response_spec.rb
 - spec/swagger_v2/api_swagger_v2_response_with_examples_spec.rb
+- spec/swagger_v2/api_swagger_v2_response_with_headers_spec.rb
 - spec/swagger_v2/api_swagger_v2_spec.rb
 - spec/swagger_v2/api_swagger_v2_status_codes_spec.rb
 - spec/swagger_v2/api_swagger_v2_type-format_spec.rb

data/.document

@@ -1,5 +0,0 @@
-lib/**/*.rb
-bin/*
-- 
-features/**/*.feature
-LICENSE.txt