grape-swagger 0.34.1 → 1.2.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (35) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +83 -0
  3. data/.travis.yml +15 -12
  4. data/CHANGELOG.md +44 -4
  5. data/Gemfile +9 -4
  6. data/README.md +123 -11
  7. data/UPGRADING.md +30 -0
  8. data/grape-swagger.gemspec +1 -1
  9. data/lib/grape-swagger.rb +2 -2
  10. data/lib/grape-swagger/doc_methods/build_model_definition.rb +53 -2
  11. data/lib/grape-swagger/doc_methods/data_type.rb +6 -6
  12. data/lib/grape-swagger/doc_methods/operation_id.rb +2 -2
  13. data/lib/grape-swagger/doc_methods/parse_params.rb +19 -4
  14. data/lib/grape-swagger/endpoint.rb +28 -18
  15. data/lib/grape-swagger/endpoint/params_parser.rb +12 -5
  16. data/lib/grape-swagger/rake/oapi_tasks.rb +10 -2
  17. data/lib/grape-swagger/version.rb +1 -1
  18. data/spec/issues/427_entity_as_string_spec.rb +1 -1
  19. data/spec/issues/430_entity_definitions_spec.rb +7 -5
  20. data/spec/issues/784_extensions_on_params_spec.rb +38 -0
  21. data/spec/lib/data_type_spec.rb +14 -2
  22. data/spec/lib/endpoint/params_parser_spec.rb +2 -1
  23. data/spec/lib/endpoint_spec.rb +1 -1
  24. data/spec/lib/oapi_tasks_spec.rb +15 -5
  25. data/spec/support/empty_model_parser.rb +1 -2
  26. data/spec/support/mock_parser.rb +1 -2
  27. data/spec/support/model_parsers/entity_parser.rb +1 -1
  28. data/spec/support/model_parsers/representable_parser.rb +1 -1
  29. data/spec/swagger_v2/api_swagger_v2_hide_param_spec.rb +14 -3
  30. data/spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb +2 -2
  31. data/spec/swagger_v2/boolean_params_spec.rb +1 -1
  32. data/spec/swagger_v2/inheritance_and_discriminator_spec.rb +56 -0
  33. data/spec/swagger_v2/reference_entity_spec.rb +74 -29
  34. data/spec/swagger_v2/security_requirement_spec.rb +2 -2
  35. metadata +15 -17
@@ -49,14 +49,26 @@ describe GrapeSwagger::DocMethods::DataType do
49
49
  it { is_expected.to eq 'MyInteger' }
50
50
  end
51
51
 
52
+ describe 'Types in array with inherited entity_name' do
53
+ before do
54
+ stub_const 'EntityBase', Class.new
55
+ allow(EntityBase).to receive(:entity_name).and_return 'MyInteger'
56
+ stub_const 'MyEntity', Class.new(EntityBase)
57
+ end
58
+
59
+ let(:value) { { type: '[MyEntity]' } }
60
+
61
+ it { is_expected.to eq 'MyInteger' }
62
+ end
63
+
52
64
  describe 'Rack::Multipart::UploadedFile' do
53
65
  let(:value) { { type: Rack::Multipart::UploadedFile } }
54
66
 
55
67
  it { is_expected.to eq 'file' }
56
68
  end
57
69
 
58
- describe 'Virtus::Attribute::Boolean' do
59
- let(:value) { { type: Virtus::Attribute::Boolean } }
70
+ describe 'Grape::API::Boolean' do
71
+ let(:value) { { type: Grape::API::Boolean } }
60
72
 
61
73
  it { is_expected.to eq 'boolean' }
62
74
  end
@@ -5,8 +5,9 @@ require 'spec_helper'
5
5
  describe GrapeSwagger::Endpoint::ParamsParser do
6
6
  let(:settings) { {} }
7
7
  let(:params) { [] }
8
+ let(:endpoint) { nil }
8
9
 
9
- let(:parser) { described_class.new(params, settings) }
10
+ let(:parser) { described_class.new(params, settings, endpoint) }
10
11
 
11
12
  describe '#parse_request_params' do
12
13
  subject(:parse_request_params) { parser.parse_request_params }
@@ -49,7 +49,7 @@ describe Grape::Endpoint do
49
49
  describe 'parse_request_params' do
50
50
  let(:subject) { GrapeSwagger::Endpoint::ParamsParser }
51
51
  before do
52
- subject.send(:parse_request_params, params, {})
52
+ subject.send(:parse_request_params, params, {}, nil)
53
53
  end
54
54
 
55
55
  context 'when params do not contain an array' do
@@ -3,8 +3,8 @@
3
3
  require 'spec_helper'
4
4
 
5
5
  RSpec.describe GrapeSwagger::Rake::OapiTasks do
6
- let(:api) do
7
- item = Class.new(Grape::API) do
6
+ module Api
7
+ class Item < Grape::API
8
8
  version 'v1', using: :path
9
9
 
10
10
  namespace :item do
@@ -16,14 +16,24 @@ RSpec.describe GrapeSwagger::Rake::OapiTasks do
16
16
  end
17
17
  end
18
18
 
19
- Class.new(Grape::API) do
19
+ class Base < Grape::API
20
20
  prefix :api
21
- mount item
21
+ mount Api::Item
22
22
  add_swagger_documentation add_version: true
23
23
  end
24
24
  end
25
25
 
26
- subject { described_class.new(api) }
26
+ subject { described_class.new(Api::Base) }
27
+
28
+ describe '.new' do
29
+ it 'accepts class name as a constant' do
30
+ expect(described_class.new(::Api::Base).send(:api_class)).to eq(Api::Base)
31
+ end
32
+
33
+ it 'accepts class name as a string' do
34
+ expect(described_class.new('::Api::Base').send(:api_class)).to eq(Api::Base)
35
+ end
36
+ end
27
37
 
28
38
  describe '#make_request' do
29
39
  describe 'complete documentation' do
@@ -5,8 +5,7 @@ end
5
5
 
6
6
  module GrapeSwagger
7
7
  class EmptyModelParser
8
- attr_reader :model
9
- attr_reader :endpoint
8
+ attr_reader :model, :endpoint
10
9
 
11
10
  def initialize(model, endpoint)
12
11
  @model = model
@@ -2,8 +2,7 @@
2
2
 
3
3
  module GrapeSwagger
4
4
  class MockParser
5
- attr_reader :model
6
- attr_reader :endpoint
5
+ attr_reader :model, :endpoint
7
6
 
8
7
  def initialize(model, endpoint)
9
8
  @model = model
@@ -116,7 +116,7 @@ RSpec.shared_context 'entity swagger example' do
116
116
  expose :prop_time, documentation: { type: Time, desc: 'prop_time description' }
117
117
  expose :prop_password, documentation: { type: 'password', desc: 'prop_password description' }
118
118
  expose :prop_email, documentation: { type: 'email', desc: 'prop_email description' }
119
- expose :prop_boolean, documentation: { type: Virtus::Attribute::Boolean, desc: 'prop_boolean description' }
119
+ expose :prop_boolean, documentation: { type: Grape::API::Boolean, desc: 'prop_boolean description' }
120
120
  expose :prop_file, documentation: { type: File, desc: 'prop_file description' }
121
121
  expose :prop_json, documentation: { type: JSON, desc: 'prop_json description' }
122
122
  end
@@ -186,7 +186,7 @@ RSpec.shared_context 'representable swagger example' do
186
186
  property :prop_time, documentation: { type: Time, desc: 'prop_time description' }
187
187
  property :prop_password, documentation: { type: 'password', desc: 'prop_password description' }
188
188
  property :prop_email, documentation: { type: 'email', desc: 'prop_email description' }
189
- property :prop_boolean, documentation: { type: Virtus::Attribute::Boolean, desc: 'prop_boolean description' }
189
+ property :prop_boolean, documentation: { type: Grape::API::Boolean, desc: 'prop_boolean description' }
190
190
  property :prop_file, documentation: { type: File, desc: 'prop_file description' }
191
191
  property :prop_json, documentation: { type: JSON, desc: 'prop_json description' }
192
192
  end
@@ -7,12 +7,19 @@ describe 'hidden flag enables a single endpoint parameter to be excluded from th
7
7
  before :all do
8
8
  module TheApi
9
9
  class HideParamsApi < Grape::API
10
+ helpers do
11
+ def resource_owner
12
+ '123'
13
+ end
14
+ end
15
+
10
16
  namespace :flat_params_endpoint do
11
17
  desc 'This is a endpoint with a flat parameter hierarchy'
12
18
  params do
13
19
  requires :name, type: String, documentation: { desc: 'name' }
14
20
  optional :favourite_color, type: String, documentation: { desc: 'I should not be anywhere', hidden: true }
15
- optional :proc_param, type: String, documentation: { desc: 'I should not be anywhere', hidden: -> { true } }
21
+ optional :proc_param, type: String, documentation: { desc: 'I should not be anywhere', hidden: proc { true } }
22
+ optional :proc_with_token, type: String, documentation: { desc: 'I may be somewhere', hidden: proc { false } }
16
23
  end
17
24
 
18
25
  post do
@@ -50,7 +57,7 @@ describe 'hidden flag enables a single endpoint parameter to be excluded from th
50
57
  end
51
58
  end
52
59
 
53
- add_swagger_documentation
60
+ add_swagger_documentation token_owner: 'resource_owner'
54
61
  end
55
62
  end
56
63
  end
@@ -63,9 +70,13 @@ describe 'hidden flag enables a single endpoint parameter to be excluded from th
63
70
  JSON.parse(last_response.body)
64
71
  end
65
72
 
66
- specify do
73
+ it 'ignores parameters that are explicitly hidden' do
67
74
  expect(subject['paths']['/flat_params_endpoint']['post']['parameters'].map { |p| p['name'] }).not_to include('favourite_color', 'proc_param')
68
75
  end
76
+
77
+ it 'allows procs to consult the token_owner' do
78
+ expect(subject['paths']['/flat_params_endpoint']['post']['parameters'].map { |p| p['name'] }).to include('proc_with_token')
79
+ end
69
80
  end
70
81
 
71
82
  describe 'nested parameter hierarchy' do
@@ -189,7 +189,7 @@ describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `h
189
189
  'type' => 'object',
190
190
  'properties' => {
191
191
  'data' => {
192
- '$ref' => '#/definitions/ApiResponse',
192
+ '$ref' => '#/definitions/NestedModule_ApiResponse',
193
193
  'description' => 'request data'
194
194
  }
195
195
  },
@@ -207,7 +207,7 @@ describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `h
207
207
  end
208
208
 
209
209
  specify do
210
- expect(subject['definitions']['ApiResponse']).not_to be_nil
210
+ expect(subject['definitions']['NestedModule_ApiResponse']).not_to be_nil
211
211
  end
212
212
 
213
213
  specify do
@@ -8,7 +8,7 @@ describe 'Boolean Params' do
8
8
  format :json
9
9
 
10
10
  params do
11
- requires :a_boolean, type: Virtus::Attribute::Boolean
11
+ requires :a_boolean, type: Grape::API::Boolean
12
12
  end
13
13
  post :splines do
14
14
  end
@@ -0,0 +1,56 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'spec_helper'
4
+
5
+ describe 'Inheritance and Discriminator' do
6
+ before :all do
7
+ module InheritanceTest
8
+ module Entities
9
+ # example from https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#models-with-polymorphism-supports
10
+ class Pet < Grape::Entity
11
+ expose :type, documentation: {
12
+ type: 'string',
13
+ is_discriminator: true,
14
+ required: true
15
+ }
16
+ expose :name, documentation: {
17
+ type: 'string',
18
+ required: true
19
+ }
20
+ end
21
+
22
+ class Cat < Pet
23
+ expose :huntingSkill, documentation: {
24
+ type: 'string',
25
+ description: 'The measured skill for hunting',
26
+ default: 'lazy',
27
+ values: %w[
28
+ clueless
29
+ lazy
30
+ adventurous
31
+ aggressive
32
+ ]
33
+ }
34
+ end
35
+ end
36
+ class NameApi < Grape::API
37
+ add_swagger_documentation models: [Entities::Pet, Entities::Cat]
38
+ end
39
+ end
40
+ end
41
+
42
+ context 'Parent model' do
43
+ let(:app) { InheritanceTest::NameApi }
44
+
45
+ subject do
46
+ get '/swagger_doc'
47
+ JSON.parse(last_response.body)['definitions']
48
+ end
49
+
50
+ specify do
51
+ subject['InheritanceTest_Entities_Pet'].key?('discriminator')
52
+ subject['InheritanceTest_Entities_Pet']['discriminator'] = 'type'
53
+ subject['InheritanceTest_Entities_Cat'].key?('allOf')
54
+ end
55
+ end
56
+ end
@@ -22,6 +22,20 @@ describe 'referenceEntity' do
22
22
  expose :title, documentation: { type: 'string', desc: 'Title of the kind.' }
23
23
  expose :something, documentation: { type: Something, desc: 'Something interesting.' }
24
24
  end
25
+
26
+ class Base < Grape::Entity
27
+ def self.entity_name
28
+ parts = to_s.split('::')
29
+
30
+ "MyAPI::#{parts.last}"
31
+ end
32
+
33
+ expose :title, documentation: { type: 'string', desc: 'Title of the parent.' }
34
+ end
35
+
36
+ class Child < Base
37
+ expose :child, documentation: { type: 'string', desc: 'Child property.' }
38
+ end
25
39
  end
26
40
 
27
41
  class ResponseModelApi < Grape::API
@@ -40,6 +54,16 @@ describe 'referenceEntity' do
40
54
  present kind, with: Entities::Kind
41
55
  end
42
56
 
57
+ desc 'This returns a child entity',
58
+ entity: Entities::Child,
59
+ http_codes: [
60
+ { code: 200, message: 'OK', model: Entities::Child }
61
+ ]
62
+ get '/child' do
63
+ child = OpenStruct.new text: 'child'
64
+ present child, with: Entities::Child
65
+ end
66
+
43
67
  add_swagger_documentation # models: [MyAPI::Entities::Something, MyAPI::Entities::Kind]
44
68
  end
45
69
  end
@@ -49,36 +73,57 @@ describe 'referenceEntity' do
49
73
  MyAPI::ResponseModelApi
50
74
  end
51
75
 
52
- subject do
53
- get '/swagger_doc/kind'
54
- JSON.parse(last_response.body)
76
+ describe 'kind' do
77
+ subject do
78
+ get '/swagger_doc/kind'
79
+ JSON.parse(last_response.body)
80
+ end
81
+
82
+ it 'should document specified models' do
83
+ expect(subject['paths']['/kind']['get']['parameters']).to eq [{
84
+ 'in' => 'query',
85
+ 'name' => 'something',
86
+ 'description' => 'Something interesting.',
87
+ 'type' => 'SomethingCustom',
88
+ 'required' => false
89
+ }]
90
+
91
+ expect(subject['definitions'].keys).to include 'SomethingCustom'
92
+ expect(subject['definitions']['SomethingCustom']).to eq(
93
+ 'type' => 'object', 'properties' => { 'text' => { 'type' => 'string', 'description' => 'Content of something.' } }
94
+ )
95
+
96
+ expect(subject['definitions'].keys).to include 'KindCustom'
97
+ expect(subject['definitions']['KindCustom']).to eq(
98
+ 'type' => 'object',
99
+ 'properties' => {
100
+ 'title' => { 'type' => 'string', 'description' => 'Title of the kind.' },
101
+ 'something' => {
102
+ '$ref' => '#/definitions/SomethingCustom',
103
+ 'description' => 'Something interesting.'
104
+ }
105
+ },
106
+ 'description' => 'This returns kind and something or an error'
107
+ )
108
+ end
55
109
  end
56
110
 
57
- it 'should document specified models' do
58
- expect(subject['paths']['/kind']['get']['parameters']).to eq [{
59
- 'in' => 'query',
60
- 'name' => 'something',
61
- 'description' => 'Something interesting.',
62
- 'type' => 'SomethingCustom',
63
- 'required' => false
64
- }]
65
-
66
- expect(subject['definitions'].keys).to include 'SomethingCustom'
67
- expect(subject['definitions']['SomethingCustom']).to eq(
68
- 'type' => 'object', 'properties' => { 'text' => { 'type' => 'string', 'description' => 'Content of something.' } }
69
- )
70
-
71
- expect(subject['definitions'].keys).to include 'KindCustom'
72
- expect(subject['definitions']['KindCustom']).to eq(
73
- 'type' => 'object',
74
- 'properties' => {
75
- 'title' => { 'type' => 'string', 'description' => 'Title of the kind.' },
76
- 'something' => {
77
- '$ref' => '#/definitions/SomethingCustom',
78
- 'description' => 'Something interesting.'
79
- }
80
- },
81
- 'description' => 'This returns kind and something or an error'
82
- )
111
+ describe 'child' do
112
+ subject do
113
+ get '/swagger_doc/child'
114
+ JSON.parse(last_response.body)
115
+ end
116
+
117
+ it 'should document specified models' do
118
+ expect(subject['definitions'].keys).to include 'MyAPI::Child'
119
+ expect(subject['definitions']['MyAPI::Child']).to eq(
120
+ 'type' => 'object',
121
+ 'properties' => {
122
+ 'title' => { 'type' => 'string', 'description' => 'Title of the parent.' },
123
+ 'child' => { 'type' => 'string', 'description' => 'Child property.' }
124
+ },
125
+ 'description' => 'This returns a child entity'
126
+ )
127
+ end
83
128
  end
84
129
  end
@@ -5,7 +5,7 @@ require 'spec_helper'
5
5
  describe 'security requirement on endpoint method' do
6
6
  def app
7
7
  Class.new(Grape::API) do
8
- desc 'Endpoint with security requirement', security: [oauth_pets: ['read:pets', 'write:pets']]
8
+ desc 'Endpoint with security requirement', security: [{ oauth_pets: ['read:pets', 'write:pets'] }]
9
9
  get '/with_security' do
10
10
  { foo: 'bar' }
11
11
  end
@@ -37,7 +37,7 @@ describe 'security requirement on endpoint method' do
37
37
  end
38
38
 
39
39
  it 'defines the security requirement on the endpoint method' do
40
- expect(subject['paths']['/with_security']['get']['security']).to eql ['oauth_pets' => ['read:pets', 'write:pets']]
40
+ expect(subject['paths']['/with_security']['get']['security']).to eql [{ 'oauth_pets' => ['read:pets', 'write:pets'] }]
41
41
  end
42
42
 
43
43
  it 'defines an empty security requirement on the endpoint method' do
metadata CHANGED
@@ -1,36 +1,30 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: grape-swagger
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.34.1
4
+ version: 1.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tim Vandecasteele
8
- autorequire:
8
+ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2020-01-11 00:00:00.000000000 Z
11
+ date: 2020-07-15 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: grape
15
15
  requirement: !ruby/object:Gem::Requirement
16
16
  requirements:
17
- - - ">="
17
+ - - "~>"
18
18
  - !ruby/object:Gem::Version
19
- version: 0.16.2
20
- - - "<"
21
- - !ruby/object:Gem::Version
22
- version: 1.3.0
19
+ version: '1.3'
23
20
  type: :runtime
24
21
  prerelease: false
25
22
  version_requirements: !ruby/object:Gem::Requirement
26
23
  requirements:
27
- - - ">="
28
- - !ruby/object:Gem::Version
29
- version: 0.16.2
30
- - - "<"
24
+ - - "~>"
31
25
  - !ruby/object:Gem::Version
32
- version: 1.3.0
33
- description:
26
+ version: '1.3'
27
+ description:
34
28
  email:
35
29
  - tim.vandecasteele@gmail.com
36
30
  executables: []
@@ -101,6 +95,7 @@ files:
101
95
  - spec/issues/650_params_array_spec.rb
102
96
  - spec/issues/680_keep_204_error_schemas_spec.rb
103
97
  - spec/issues/751_deeply_nested_objects_spec.rb
98
+ - spec/issues/784_extensions_on_params_spec.rb
104
99
  - spec/lib/data_type_spec.rb
105
100
  - spec/lib/endpoint/params_parser_spec.rb
106
101
  - spec/lib/endpoint_spec.rb
@@ -161,6 +156,7 @@ files:
161
156
  - spec/swagger_v2/guarded_endpoint_spec.rb
162
157
  - spec/swagger_v2/hide_api_spec.rb
163
158
  - spec/swagger_v2/host_spec.rb
159
+ - spec/swagger_v2/inheritance_and_discriminator_spec.rb
164
160
  - spec/swagger_v2/mount_override_api_spec.rb
165
161
  - spec/swagger_v2/mounted_target_class_spec.rb
166
162
  - spec/swagger_v2/namespace_tags_prefix_spec.rb
@@ -184,7 +180,7 @@ homepage: https://github.com/ruby-grape/grape-swagger
184
180
  licenses:
185
181
  - MIT
186
182
  metadata: {}
187
- post_install_message:
183
+ post_install_message:
188
184
  rdoc_options: []
189
185
  require_paths:
190
186
  - lib
@@ -199,8 +195,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
199
195
  - !ruby/object:Gem::Version
200
196
  version: '0'
201
197
  requirements: []
202
- rubygems_version: 3.1.2
203
- signing_key:
198
+ rubygems_version: 3.1.4
199
+ signing_key:
204
200
  specification_version: 4
205
201
  summary: Add auto generated documentation to your Grape API that can be displayed
206
202
  with Swagger.
@@ -223,6 +219,7 @@ test_files:
223
219
  - spec/issues/650_params_array_spec.rb
224
220
  - spec/issues/680_keep_204_error_schemas_spec.rb
225
221
  - spec/issues/751_deeply_nested_objects_spec.rb
222
+ - spec/issues/784_extensions_on_params_spec.rb
226
223
  - spec/lib/data_type_spec.rb
227
224
  - spec/lib/endpoint/params_parser_spec.rb
228
225
  - spec/lib/endpoint_spec.rb
@@ -283,6 +280,7 @@ test_files:
283
280
  - spec/swagger_v2/guarded_endpoint_spec.rb
284
281
  - spec/swagger_v2/hide_api_spec.rb
285
282
  - spec/swagger_v2/host_spec.rb
283
+ - spec/swagger_v2/inheritance_and_discriminator_spec.rb
286
284
  - spec/swagger_v2/mount_override_api_spec.rb
287
285
  - spec/swagger_v2/mounted_target_class_spec.rb
288
286
  - spec/swagger_v2/namespace_tags_prefix_spec.rb