grape-swagger 0.34.0 → 1.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.rubocop.yml +55 -0
- data/.travis.yml +14 -10
- data/CHANGELOG.md +37 -4
- data/Gemfile +9 -4
- data/README.md +123 -10
- data/UPGRADING.md +30 -0
- data/grape-swagger.gemspec +1 -1
- data/lib/grape-swagger.rb +1 -0
- data/lib/grape-swagger/doc_methods/build_model_definition.rb +53 -2
- data/lib/grape-swagger/doc_methods/data_type.rb +6 -6
- data/lib/grape-swagger/doc_methods/operation_id.rb +2 -2
- data/lib/grape-swagger/doc_methods/parse_params.rb +19 -4
- data/lib/grape-swagger/endpoint.rb +11 -11
- data/lib/grape-swagger/endpoint/params_parser.rb +12 -5
- data/lib/grape-swagger/rake/oapi_tasks.rb +10 -2
- data/lib/grape-swagger/version.rb +1 -1
- data/spec/issues/427_entity_as_string_spec.rb +1 -1
- data/spec/issues/430_entity_definitions_spec.rb +7 -5
- data/spec/issues/784_extensions_on_params_spec.rb +38 -0
- data/spec/lib/data_type_spec.rb +14 -2
- data/spec/lib/endpoint/params_parser_spec.rb +2 -1
- data/spec/lib/endpoint_spec.rb +1 -1
- data/spec/lib/oapi_tasks_spec.rb +15 -5
- data/spec/support/model_parsers/entity_parser.rb +1 -1
- data/spec/support/model_parsers/representable_parser.rb +1 -1
- data/spec/swagger_v2/api_swagger_v2_hide_param_spec.rb +14 -3
- data/spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb +2 -2
- data/spec/swagger_v2/boolean_params_spec.rb +1 -1
- data/spec/swagger_v2/inheritance_and_discriminator_spec.rb +56 -0
- data/spec/swagger_v2/reference_entity_spec.rb +74 -29
- metadata +14 -16
@@ -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:
|
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:
|
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:
|
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 { |token_owner = nil| token_owner.nil? } }
|
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
|
-
|
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/
|
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']['
|
210
|
+
expect(subject['definitions']['NestedModule_ApiResponse']).not_to be_nil
|
211
211
|
end
|
212
212
|
|
213
213
|
specify do
|
@@ -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
|
-
|
53
|
-
|
54
|
-
|
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
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
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
|
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:
|
4
|
+
version: 1.2.0
|
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
|
+
date: 2020-07-01 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:
|
20
|
-
- - "<="
|
21
|
-
- !ruby/object:Gem::Version
|
22
|
-
version: 1.2.5
|
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.
|
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
|
@@ -200,7 +196,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
200
196
|
version: '0'
|
201
197
|
requirements: []
|
202
198
|
rubygems_version: 3.1.2
|
203
|
-
signing_key:
|
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
|