grape-swagger 0.25.0 → 0.25.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 65693b18186fa5904b3f3012ac7a94cec5d90a44
-  data.tar.gz: d7e2b413a40e081cd155e76a554b1d7f3c532c9f
+  metadata.gz: 05e6839d574113d1a31a0b1758bb9426174b2dd5
+  data.tar.gz: ad8936f7e557193a2502e95d64c8ef7c90a04684
 SHA512:
-  metadata.gz: 2e998b82aba1e6252f6e63fe9dcc2ea53cb6b8aa4f384de774ed71cae5855158378e3e8ecdf920742ec2f5a196434f80c7798713d75d2b1a593e5aed7b6b8719
-  data.tar.gz: 3047cca817fd55c251717de9cf015dc26272f6da6996b67e317b2e058c18ff02fdd42bc5b1835da03500e8096cfc7da4ba1b813b012b5ee1e1993e18d413b502
+  metadata.gz: c0ed0cbb32dbe1998964427703cee5e7399f67dad503ba1bd04569b913343bb67e5782da445340e4eda390a1f0c424edd08546a06189047de7d2f9ce3bc55463
+  data.tar.gz: f01ba1a06247a146fed67950c98257d5708965531558f18468391da001e848aea03c2a80e3e19431337b10a2d912783ba8e50ed0fcedca3285ac7c637364d7ed

data/.rubocop_todo.yml

@@ -18,7 +18,7 @@ Metrics/BlockLength:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 240
+  Max: 247
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:

data/CHANGELOG.md

@@ -8,6 +8,19 @@
 
 * Your contribution here.
 
+
+### 0.25.1 (November 29, 2016)
+
+#### Features
+
+* [#531](https://github.com/ruby-grape/grape-swagger/pull/531): UUID data_type format support - [@migmartri](https://github.com/migmartri).
+* [#534](https://github.com/ruby-grape/grape-swagger/pull/534): Allows to overwrite defaults status codes - [@LeFnord](https://github.com/LeFnord).
+
+#### Fixes
+
+* [#540](https://github.com/ruby-grape/grape-swagger/pull/540): Corrects exposing of array in post body - [@LeFnord](https://github.com/LeFnord).
+* [#509](https://github.com/ruby-grape/grape-swagger/pull/509), [#529](https://github.com/ruby-grape/grape-swagger/pull/529): Making parent-less routes working - [@mur-wtag](https://github.com/mur-wtag).
+
 ### 0.25.0 (October 31, 2016)
 
 #### Features

data/README.md

@@ -52,6 +52,8 @@ grape-swagger | swagger spec | grape                   | grape-entity | represen
 0.20.3        |     2.0      | >= 0.12.0 ... ~> 0.16.2 | ~> 0.5.1     | n/a           |
 0.21.0        |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
 0.23.0        |     2.0      | >= 0.12.0 ... <= 0.17.0 | <= 0.5.1     | >= 2.4.1      |
+0.24.0        |     2.0      | >= 0.12.0 ... <= 0.18.0 | <= 0.5.1     | >= 2.4.1      |
+0.25.0        |     2.0      | >= 0.14.0 ... <= 0.18.0 | <= 0.5.2     | >= 2.4.1      |
 
 <a name="swagger-spec" />
 ## Swagger-Spec
@@ -402,6 +404,7 @@ add_swagger_documentation \
 * [Hiding parameters](#hiding-parameters)
 * [Setting a Swagger default value](#default-value)
 * [Response documentation](#response)
+* [Changing default status codes](#change-status)
 * [Extensions](#extensions)
 
 
@@ -750,7 +753,7 @@ You can also document the HTTP status codes with a description and a specified m
 In the following cases, the schema ref would be taken from route.
 
 ```ruby
-desc 'thing', failures: [ { code: 400, message: "Invalid parameter entry" } ]
+desc 'thing', failures: [ { code: 400, message: 'Invalid parameter entry' } ]
 get '/thing' do
   ...
 end
@@ -759,7 +762,7 @@ end
 ```ruby
 desc 'thing' do
   params Entities::Something.documentation
-  failures [ { code: 400, message: "Invalid parameter entry" } ]
+  failures [ { code: 400, message: 'Invalid parameter entry' } ]
 end
 get '/thing' do
   ...
@@ -768,8 +771,8 @@ end
 
 ```ruby
 get '/thing', failures: [
-  { code: 200, message: 'Ok' },
-  { code: 400, message: "Invalid parameter entry" }
+  { code: 400, message: 'Invalid parameter entry' },
+  { code: 404, message: 'Not authorized' },
 ] do
   ...
 end
@@ -778,13 +781,13 @@ end
 By adding a `model` key, e.g. this would be taken.
 ```ruby
 get '/thing', failures: [
-  { code: 200, message: 'Ok' },
-  { code: 422, message: "Invalid parameter entry", model: Entities::ApiError }
+  { code: 400, message: 'General error' },
+  { code: 422, message: 'Invalid parameter entry', model: Entities::ApiError }
 ] do
   ...
 end
 ```
-If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L121) would be taken.
+If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L210) would be taken.
 
 The result is then something like following:
 
@@ -805,6 +808,33 @@ The result is then something like following:
 },
 ```
 
+<a name="change-status" />
+#### Changing default status codes
+
+The default status codes, one could be found (-> [status codes](lib/grape-swagger/doc_methods/status_codes.rb)) can be changed to your specific needs, to achive it, you have to change it for grape itself and for the documentation.
+
+```ruby
+desc 'Get a list of stuff',
+    success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+get do
+  status 202
+  # your code comes here
+end
+…
+```
+
+```json
+"responses": {
+  "202": {
+    "description": "ok",
+    "schema": {
+      "$ref": "#/definitions/UseResponse"
+    }
+  }
+},
+```
+
+
 <a name="extensions" />
 #### Extensions
 
@@ -926,7 +956,7 @@ module API
     class Client < Grape::Entity
       expose :name, documentation: { type: 'string', desc: 'Name' }
       expose :addresses, using: Entities::Address,
-        documentation: { type: 'API::Address', desc: 'Addresses.', param_type: 'body', is_array: true }
+        documentation: { type: 'Entities::Address', desc: 'Addresses.', param_type: 'body', is_array: true }
     end
 
     class Address < Grape::Entity
@@ -937,13 +967,15 @@ module API
   class Clients < Grape::API
     version 'v1'
 
-    desc 'Clients index', params: Entities::Client.documentation
+    desc 'Clients index',
+      params: Entities::Client.documentation,
+      success: Entities::Client
     get '/clients' do
       ...
     end
   end
 
-  add_swagger_documentation models: [Entities::Client, Entities::Address]
+  add_swagger_documentation
 end
 ```
 
@@ -958,7 +990,7 @@ module API
     class Client < Grape::Entity
       expose :name, documentation: { type: 'string', desc: 'Name' }
       expose :address, using: Entities::Address,
-        documentation: { type: 'API::Address', desc: 'Addresses.', param_type: 'body', is_array: false }
+        documentation: { type: 'Entities::Address', desc: 'Addresses.', param_type: 'body', is_array: false }
     end
 
     class Address < Grape::Entity
@@ -969,13 +1001,15 @@ module API
   class Clients < Grape::API
     version 'v1'
 
-    desc 'Clients index', params: Entities::Client.documentation
+    desc 'Clients index',
+      params: Entities::Client.documentation,
+      success: Entities::Client
     get '/clients' do
       ...
     end
   end
 
-  add_swagger_documentation models: [Entities::Client, Entities::Address]
+  add_swagger_documentation
 end
 ```
 

data/lib/grape-swagger.rb

@@ -100,7 +100,7 @@ module Grape
         # iterate over each single namespace
         namespaces.each do |name, namespace|
           # get the parent route for the namespace
-          parent_route_name = name.match(%r{^/?([^/]*).*$})[1]
+          parent_route_name = extract_parent_route(name)
           parent_route = @target_class.combined_routes[parent_route_name]
           # fetch all routes that are within the current namespace
           namespace_routes = parent_route.reject do |route|
@@ -142,6 +142,12 @@ module Grape
         end
       end
 
+      def extract_parent_route(name)
+        route_name = name.match(%r{^/?([^/]*).*$})[1]
+        return route_name unless route_name.include? ':'
+        name.match(/\/[a-z]+/)[0].delete('/')
+      end
+
       def sub_routes_from(parent_route, sub_namespaces)
         sub_ns_paths = sub_namespaces.collect { |ns_name, _| ["/#{ns_name}", "/:version/#{ns_name}"] }
         sub_routes = parent_route.reject do |route|

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

@@ -83,7 +83,8 @@ module GrapeSwagger
         'dateTime' => %w(string date-time),
         'binary' => %w(string binary),
         'password' => %w(string password),
-        'email' => %w(string email)
+        'email' => %w(string email),
+        'uuid' => %w(string uuid)
       }.freeze
     end
   end

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

@@ -12,6 +12,8 @@ module GrapeSwagger
           @definitions = definitions
           unify!(params)
 
+          return correct_array_param(params) if should_correct_array?(params)
+
           params_to_move = movable_params(params)
           params << parent_definition_of_params(params_to_move, route)
 
@@ -20,6 +22,14 @@ module GrapeSwagger
 
         private
 
+        def should_correct_array?(param)
+          param.length == 1 && param.first[:in] == 'body' && param.first[:type] == 'array'
+        end
+
+        def correct_array_param(param)
+          param.first[:schema] = { type: param.first.delete(:type), items: param.first.delete(:items) }
+        end
+
         def parent_definition_of_params(params, route)
           definition_name = GrapeSwagger::DocMethods::OperationId.manipulate(parse_model(route.path))
           referenced_definition = build_definition(definition_name, params, route.request_method.downcase)

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

@@ -68,6 +68,8 @@ module GrapeSwagger
             collection_format = value_type[:documentation][:collectionFormat]
           end
 
+          param_type ||= value_type[:param_type]
+
           array_items = {}
           if definitions[value_type[:data_type]]
             array_items['$ref'] = "#/definitions/#{@parsed_param[:type]}"

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

@@ -8,6 +8,8 @@ module GrapeSwagger
             post: { code: 201, message: 'created {item}' },
             put: { code: 200, message: 'updated {item}' },
             patch: { code: 200, message: 'patched {item}' },
+            # 200 for delete would only be used, if a success entity is given,
+            # else it would be set to 204
             delete: { code: 200, message: 'deleted {item}' },
             head: { code: 200, message: 'head {item}' },
             options: { code: 200, message: 'option {item}' }

data/lib/grape-swagger/endpoint.rb

@@ -178,8 +178,8 @@ module Grape
 
     def response_object(route, markdown)
       codes = (route.http_codes || route.options[:failure] || [])
-      codes = apply_defaults(route, codes) if route.options[:ignore_defaults].nil?
 
+      codes = apply_success_codes(route) + codes
       codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2] } : x }
 
       codes.each_with_object({}) do |value, memo|
@@ -207,11 +207,19 @@ module Grape
       end
     end
 
-    def apply_defaults(route, codes)
+    def apply_success_codes(route)
       default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
-      default_code[:model] = @entity if @entity
-      default_code[:message] = route.description || default_code[:message].sub('{item}', @item)
-      [default_code] + codes
+      if @entity.is_a?(Hash)
+        default_code[:code] = @entity[:code] if @entity[:code].present?
+        default_code[:model] = @entity[:model] if @entity[:model].present?
+        default_code[:message] = @entity[:message] || route.description || default_code[:message].sub('{item}', @item)
+      else
+        default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
+        default_code[:model] = @entity if @entity
+        default_code[:message] = route.description || default_code[:message].sub('{item}', @item)
+      end
+
+      [default_code]
     end
 
     def tag_object(route)

data/lib/grape-swagger/version.rb

@@ -1,3 +1,3 @@
 module GrapeSwagger
-  VERSION = '0.25.0'.freeze
+  VERSION = '0.25.1'.freeze
 end

data/spec/issues/533_specify_status_code_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe '#533 specify status codes' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_533 do
+        desc 'Get a list of stuff',
+             success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+        get do
+          status 202
+          { foo: 'that is the response' }
+        end
+
+        desc 'Post some stuff',
+             success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+        post do
+          status 202
+          { foo: 'that is the response' }
+        end
+
+        desc 'Post some stuff',
+             success: { code: 204, message: 'a changed status code' }
+        patch do
+          status 204
+        end
+
+        desc 'Delete some stuff',
+             success: { code: 203 }
+        delete do
+          status 203
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['paths']['/issue_533']
+  end
+
+  let(:get_response) { get '/issue_533' }
+  specify { expect(get_response.status).to eql 202 }
+  let(:get_response_documentation) { subject['get']['responses'] }
+  specify do
+    expect(get_response_documentation.keys.first).to eql '202'
+    expect(get_response_documentation['202']).to include 'schema'
+  end
+
+  let(:post_response) { post '/issue_533' }
+  specify { expect(post_response.status).to eql 202 }
+  let(:post_response_documentation) { subject['post']['responses'] }
+  specify do
+    expect(post_response_documentation.keys.first).to eql '202'
+    expect(post_response_documentation['202']).to include 'schema'
+  end
+
+  let(:patch_response) { patch '/issue_533' }
+  specify { expect(patch_response.status).to eql 204 }
+  let(:patch_response_documentation) { subject['patch']['responses'] }
+  specify do
+    expect(patch_response_documentation.keys.first).to eql '204'
+    expect(patch_response_documentation['204']).not_to include 'schema'
+  end
+
+  let(:delete_response) { delete '/issue_533' }
+  specify { expect(delete_response.status).to eql 203 }
+  let(:delete_response_documentation) { subject['delete']['responses'] }
+  specify do
+    expect(delete_response_documentation.keys.first).to eql '203'
+    expect(delete_response_documentation['203']).not_to include 'schema'
+  end
+end

data/spec/issues/539_array_post_body.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+require 'grape-entity'
+require 'grape-swagger-entity'
+
+describe '#427 nested entity given as string' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_427 do
+        class Element < Grape::Entity
+          expose :id
+          expose :description
+          expose :role
+        end
+
+        class ArrayOfElements < Grape::Entity
+          expose :elements,
+                 documentation: {
+                   type: Element, is_array: true, param_type: 'body', required: true
+                 }
+        end
+
+        desc 'create account',
+             params: ArrayOfElements.documentation
+        post do
+          present params
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  let(:parameters) { subject['paths']['/issue_427']['post']['parameters'] }
+  let(:definitions) { subject['definitions'] }
+
+  specify do
+    expect(parameters).to eql(
+      [
+        {
+          'in' => 'body', 'name' => 'elements', 'required' => true, 'schema' => {
+            'type' => 'array', 'items' => { '$ref' => '#/definitions/Element' }
+          }
+        }
+      ]
+    )
+
+    expect(definitions).to eql(
+      'Element' => {
+        'type' => 'object',
+        'properties' => {
+          'id' => { 'type' => 'string' },
+          'description' => { 'type' => 'string' },
+          'role' => { 'type' => 'string' }
+        }
+      }
+    )
+  end
+end

data/spec/support/namespace_tags.rb

@@ -66,6 +66,23 @@ RSpec.shared_context 'namespace example' do
           end
         end
       end
+
+      class ParentLessNamespaceApi < Grape::API
+        route_param :animal do
+          route_param :breed do
+            resource :queues do
+              route_param :queue_id do
+                resource :reservations do
+                  desc 'Lists all reservations specific type of animal of specific breed in specific queue'
+                  get do
+                    { bla: 'Bla Black' }
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
     end
   end
 end

data/spec/swagger_v2/api_swagger_v2_ignore_defaults_spec.rb

@@ -8,12 +8,12 @@ describe 'swagger spec v2.0' do
       format :json
 
       desc 'This creates Thing after a delay',
-           success: Entities::Something
+           success: { code: 202, message: 'OK', model: Entities::Something }
       params do
         requires :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
         requires :links, type: Array, documentation: { type: 'link', is_array: true }
       end
-      post '/delay_thing', http_codes: [{ code: 202, message: 'OK' }], ignore_defaults: true do
+      post '/delay_thing' do
         status 202
       end
 
@@ -40,7 +40,7 @@ describe 'swagger spec v2.0' do
   let(:json) { JSON.parse(last_response.body) }
 
   it 'only returns one response if ignore_defaults is specified' do
-    expect(json['paths']['/delay_thing']['post']['responses']).to eq('202' => { 'description' => 'OK' })
+    expect(json['paths']['/delay_thing']['post']['responses']).to eq('202' => { 'description' => 'OK', 'schema' => { '$ref' => '#/definitions/Something' } })
     expect(json['paths']['/delay_thing']['post']['responses'].keys).not_to include '201'
   end
 end

data/spec/swagger_v2/parent_less_namespace.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe 'a parent less namespace' do
+  include_context 'namespace example'
+
+  before :all do
+    class ParentLessApi < Grape::API
+      prefix :api
+      mount TheApi::ParentLessNamespaceApi
+      add_swagger_documentation version: 'v1'
+    end
+  end
+
+  def app
+    ParentLessApi
+  end
+
+  describe 'retrieves swagger-documentation on /swagger_doc' do
+    let(:route_name) { ':animal/:breed/queues/:queue_id/reservations' }
+    subject do
+      get '/api/swagger_doc.json'
+      JSON.parse(last_response.body)
+    end
+
+    context 'not raises error' do
+      specify do
+        expect(subject['tags']).to eql([{ 'name' => 'queues', 'description' => 'Operations about queues' }])
+        expect(subject['paths']['/api/{animal}/{breed}/queues/{queue_id}/reservations']['get']['operationId'])
+          .to eql('getApiAnimalBreedQueuesQueueIdReservations')
+      end
+    end
+
+    context 'raises error' do
+      specify do
+        allow_any_instance_of(ParentLessApi)
+          .to receive(:extract_parent_route).with(route_name).and_return(':animal') # BUT IT'S NOT STUBBING, CAUSE IT'S A PRIVATE METHODS
+        expect { subject }.to raise_error NoMethodError
+      end
+    end
+
+    context 'ParentLessApi.extract_parent_route' do
+      specify do
+        expect(ParentLessApi.send(:extract_parent_route, route_name)).to eq('queues')
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.25.1
 platform: ruby
 authors:
 - Tim Vandecasteele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-31 00:00:00.000000000 Z
+date: 2016-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -261,6 +261,8 @@ files:
 - spec/issues/403_versions_spec.rb
 - spec/issues/427_entity_as_string_spec.rb
 - spec/issues/430_entity_definitions_spec.rb
+- spec/issues/533_specify_status_code_spec.rb
+- spec/issues/539_array_post_body.rb
 - spec/lib/data_type_spec.rb
 - spec/lib/endpoint_spec.rb
 - spec/lib/extensions_spec.rb
@@ -324,6 +326,7 @@ files:
 - spec/swagger_v2/params_array_spec.rb
 - spec/swagger_v2/params_hash_spec.rb
 - spec/swagger_v2/params_nested_spec.rb
+- spec/swagger_v2/parent_less_namespace.rb
 - spec/swagger_v2/reference_entity.rb
 - spec/swagger_v2/security_requirement_spec.rb
 - spec/swagger_v2/simple_mounted_api_spec.rb
@@ -348,7 +351,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.7
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Add auto generated documentation to your Grape API that can be displayed
@@ -357,6 +360,8 @@ test_files:
 - spec/issues/403_versions_spec.rb
 - spec/issues/427_entity_as_string_spec.rb
 - spec/issues/430_entity_definitions_spec.rb
+- spec/issues/533_specify_status_code_spec.rb
+- spec/issues/539_array_post_body.rb
 - spec/lib/data_type_spec.rb
 - spec/lib/endpoint_spec.rb
 - spec/lib/extensions_spec.rb
@@ -420,6 +425,7 @@ test_files:
 - spec/swagger_v2/params_array_spec.rb
 - spec/swagger_v2/params_hash_spec.rb
 - spec/swagger_v2/params_nested_spec.rb
+- spec/swagger_v2/parent_less_namespace.rb
 - spec/swagger_v2/reference_entity.rb
 - spec/swagger_v2/security_requirement_spec.rb
 - spec/swagger_v2/simple_mounted_api_spec.rb