grape-swagger 0.27.1 → 0.27.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 3d4da1b29c0c251744171e78d2d8e7f9911c8b0d
4
- data.tar.gz: 24c02ffce502d8e7379fbde275c9f747f3bc07d3
3
+ metadata.gz: cd96ed3b622fb9377315f85c54a8bc7a48bca789
4
+ data.tar.gz: f422e01c1efc38591c61e0b9e547e2935b543d92
5
5
  SHA512:
6
- metadata.gz: cf0dadce63c9f23539eab02f871cbaeeccc6a39af8ca7b2e588fe3082301eed7e913ab2e77d1cbcfb7b90f56f645bad348fa5248b609677ab5a436df4026f633
7
- data.tar.gz: 6b094b917156606be769a220c74a06198b0721e54e2a456b8104baad7c1605ec1e2642d01f308778cb260e4ab7dd7313be8d913b0eef7225d32c7b2fd0f62d09
6
+ metadata.gz: 6ad5d364859f7eaef34fb16805b5ba7dbbb8c1c79c84d4b76f18d5635b17237cd11cb7a849107d24ffe6eea98c99babd8ff287dcf5c233a877d6f573f35633fc
7
+ data.tar.gz: 135704aca1becf4c1f25cfcf4c0d1ebe71357fb7d637f151d589ba26cca9c7dad00f945e6948108e632a985abfdb727a322dcb02672ed972b447ca9e5f842f27
data/CHANGELOG.md CHANGED
@@ -8,7 +8,15 @@
8
8
 
9
9
  * Your contribution here.
10
10
 
11
- ### ### 0.27.1 (April 28, 2017)
11
+ ### 0.27.2 (May 11, 2017)
12
+
13
+ #### Features
14
+
15
+ * [#608](https://github.com/ruby-grape/grape-swagger/pull/608): Support extensions on the root object - [@thogg4](https://github.com/thogg4).
16
+ * [#596](https://github.com/ruby-grape/grape-swagger/pull/596): Use route_settings for hidden and operations extensions - [@thogg4](https://github.com/thogg4).
17
+ * [#607](https://github.com/ruby-grape/grape-swagger/pull/607): Allow body parameter name to be specified - [@tjwp](https://github.com/tjwp).
18
+
19
+ ### 0.27.1 (April 28, 2017)
12
20
 
13
21
  #### Features
14
22
 
data/README.md CHANGED
@@ -458,6 +458,13 @@ Or by adding ```hidden: true``` on the verb method of the endpoint, such as `get
458
458
  get '/kittens', hidden: true do
459
459
  ```
460
460
 
461
+ Or by using a route setting:
462
+
463
+ ```ruby
464
+ route_setting :swagger, { hidden: true }
465
+ gem '/kittens' do
466
+ ```
467
+
461
468
  Endpoints can be conditionally hidden by providing a callable object such as a lambda which evaluates to the desired
462
469
  state:
463
470
 
@@ -521,6 +528,20 @@ end
521
528
  ```
522
529
 
523
530
 
531
+ #### Overriding the name of the body parameter
532
+
533
+ By default, body parameters have a generated name based on the operation. For
534
+ deeply nested resources, this name can get very long. To override the name of
535
+ body parameter add `body_name: 'post_body'` after the description.
536
+
537
+ ```ruby
538
+ namespace 'order' do
539
+ desc 'Create an order', body_name: 'post_body'
540
+ post do
541
+ ...
542
+ end
543
+ end
544
+ ```
524
545
 
525
546
  #### Defining an endpoint as an array <a name="array" />
526
547
 
@@ -885,11 +906,29 @@ end
885
906
  #### Extensions <a name="extensions" />
886
907
 
887
908
  Swagger spec2.0 supports extensions on different levels, for the moment,
888
- the documentation on `info`, `verb`, `path` and `definition` level would be supported.
909
+ the documentation on the root level object and the `info`, `verb`, `path` and `definition` levels are supported.
889
910
  The documented key would be generated from the `x` + `-` + key of the submitted hash,
890
911
  for possibilities refer to the [extensions spec](spec/lib/extensions_spec.rb).
891
912
  To get an overview *how* the extensions would be defined on grape level, see the following examples:
892
913
 
914
+ - root object extension, add a `x` key to the root hash when calling ```add_swagger_documentation```:
915
+ ```ruby
916
+ add_swagger_documentation \
917
+ x: {
918
+ some: 'stuff'
919
+ },
920
+ info: {
921
+ }
922
+ ```
923
+ this would generate:
924
+ ```json
925
+ {
926
+ "x-some": "stuff",
927
+ "info":{
928
+ }
929
+ }
930
+ ```
931
+
893
932
  - `info` extension, add a `x` key to the `info` hash when calling ```add_swagger_documentation```:
894
933
  ```ruby
895
934
  add_swagger_documentation \
@@ -919,6 +958,20 @@ this would generate:
919
958
  }
920
959
  ```
921
960
 
961
+ - `operation` extension, by setting via route settings::
962
+ ```ruby
963
+ route_setting :x_operation, { some: 'stuff' }
964
+ ```
965
+ this would generate:
966
+ ```json
967
+ "/path":{
968
+ "get":{
969
+ "…":"…",
970
+ "x-some":"stuff"
971
+ }
972
+ }
973
+ ```
974
+
922
975
  - `path` extension, by setting via route settings:
923
976
  ```ruby
924
977
  route_setting :x_path, { some: 'stuff' }
@@ -11,14 +11,23 @@ module GrapeSwagger
11
11
  add_extension_to(path[method], extension(description)) if description && extended?(description, :x)
12
12
 
13
13
  settings = route.settings
14
+ add_extensions_to_operation(settings, path, route) if settings && extended?(settings, :x_operation)
14
15
  add_extensions_to_path(settings, path) if settings && extended?(settings, :x_path)
15
16
  add_extensions_to_definition(settings, path, definitions) if settings && extended?(settings, :x_def)
16
17
  end
17
18
 
19
+ def add_extensions_to_root(settings, object)
20
+ add_extension_to(object, extension(settings)) if extended?(settings, :x)
21
+ end
22
+
18
23
  def add_extensions_to_info(settings, info)
19
24
  add_extension_to(info, extension(settings)) if extended?(settings, :x)
20
25
  end
21
26
 
27
+ def add_extensions_to_operation(settings, path, route)
28
+ add_extension_to(path[route.request_method.downcase.to_sym], extension(settings, :x_operation))
29
+ end
30
+
22
31
  def add_extensions_to_path(settings, path)
23
32
  add_extension_to(path, extension(settings, :x_path))
24
33
  end
@@ -42,9 +42,9 @@ module GrapeSwagger
42
42
 
43
43
  move_params_to_new(definition, params)
44
44
 
45
- definition[:description] = route.description if route.respond_to?(:description)
45
+ definition[:description] = route.description if route.try(:description)
46
46
 
47
- build_body_parameter(referenced_definition, definition_name)
47
+ build_body_parameter(referenced_definition, definition_name, route.options)
48
48
  end
49
49
 
50
50
  def move_params_to_new(definition, params)
@@ -150,9 +150,9 @@ module GrapeSwagger
150
150
  definition[:required].push(*value)
151
151
  end
152
152
 
153
- def build_body_parameter(reference, name)
153
+ def build_body_parameter(reference, name, options)
154
154
  {}.tap do |x|
155
- x[:name] = name
155
+ x[:name] = options[:body_name] || name
156
156
  x[:in] = 'body'
157
157
  x[:required] = true
158
158
  x[:schema] = { '$ref' => "#/definitions/#{reference}" }
@@ -23,17 +23,20 @@ module Grape
23
23
  #
24
24
  # required keys for SwaggerObject
25
25
  def swagger_object(target_class, request, options)
26
- {
27
- info: info_object(options[:info].merge(version: options[:doc_version])),
28
- swagger: '2.0',
29
- produces: content_types_for(target_class),
30
- authorizations: options[:authorizations],
26
+ object = {
27
+ info: info_object(options[:info].merge(version: options[:doc_version])),
28
+ swagger: '2.0',
29
+ produces: content_types_for(target_class),
30
+ authorizations: options[:authorizations],
31
31
  securityDefinitions: options[:security_definitions],
32
- security: options[:security],
33
- host: GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
34
- basePath: GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
35
- schemes: options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
36
- }.delete_if { |_, value| value.blank? }
32
+ security: options[:security],
33
+ host: GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
34
+ basePath: GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
35
+ schemes: options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
36
+ }
37
+
38
+ GrapeSwagger::DocMethods::Extensions.add_extensions_to_root(options, object)
39
+ object.delete_if { |_, value| value.blank? }
37
40
  end
38
41
 
39
42
  # building info object
@@ -338,7 +341,8 @@ module Grape
338
341
  end
339
342
 
340
343
  def hidden?(route, options)
341
- route_hidden = route.options[:hidden]
344
+ route_hidden = route.settings.try(:[], :swagger).try(:[], :hidden)
345
+ route_hidden = route.options[:hidden] if route.options.key?(:hidden)
342
346
  return route_hidden unless route_hidden.is_a?(Proc)
343
347
  options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call
344
348
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module GrapeSwagger
4
- VERSION = '0.27.1'
4
+ VERSION = '0.27.2'
5
5
  end
@@ -94,18 +94,13 @@ describe GrapeSwagger::DocMethods::MoveParams do
94
94
 
95
95
  describe 'parent_definition_of_params' do
96
96
  let(:path) { '/in_body' }
97
+ let(:route_options) { { requirements: {} } }
97
98
  describe 'POST' do
98
99
  let(:params) { paths[path][:post][:parameters] }
99
- let(:options) do
100
- {
101
- method: 'POST'
102
- }
103
- end
104
- let(:env) { Rack::MockRequest.env_for(path, options) }
105
- let(:request) { Grape::Request.new(env) }
100
+ let(:route) { Grape::Router::Route.new('POST', path.dup, route_options) }
106
101
 
107
102
  specify do
108
- subject.to_definition(path, params, request, definitions)
103
+ subject.to_definition(path, params, route, definitions)
109
104
  expect(params).to eql(
110
105
  [
111
106
  { name: 'InBody', in: 'body', required: true, schema: { '$ref' => '#/definitions/postInBody' } }
@@ -118,16 +113,10 @@ describe GrapeSwagger::DocMethods::MoveParams do
118
113
 
119
114
  describe 'POST' do
120
115
  let(:params) { paths['/in_body/{key}'][:put][:parameters] }
121
- let(:options) do
122
- {
123
- method: 'PUT'
124
- }
125
- end
126
- let(:env) { Rack::MockRequest.env_for(path, options) }
127
- let(:request) { Grape::Request.new(env) }
116
+ let(:route) { Grape::Router::Route.new('PUT', path.dup, route_options) }
128
117
 
129
118
  specify do
130
- subject.to_definition(path, params, request, definitions)
119
+ subject.to_definition(path, params, route, definitions)
131
120
  expect(params).to eql(
132
121
  [
133
122
  { in: 'path', name: 'key', description: nil, type: 'integer', format: 'int32', required: true },
@@ -214,9 +203,20 @@ describe GrapeSwagger::DocMethods::MoveParams do
214
203
  { name: name, in: 'body', required: true, schema: { '$ref' => "#/definitions/#{reference}" } }
215
204
  end
216
205
  specify do
217
- parameter = subject.send(:build_body_parameter, reference, name)
206
+ parameter = subject.send(:build_body_parameter, reference, name, {})
218
207
  expect(parameter).to eql expected_param
219
208
  end
209
+
210
+ describe 'body_name option specified' do
211
+ let(:route_options) { { body_name: 'body' } }
212
+ let(:expected_param) do
213
+ { name: route_options[:body_name], in: 'body', required: true, schema: { '$ref' => "#/definitions/#{reference}" } }
214
+ end
215
+ specify do
216
+ parameter = subject.send(:build_body_parameter, reference, name, route_options)
217
+ expect(parameter).to eql expected_param
218
+ end
219
+ end
220
220
  end
221
221
  end
222
222
 
@@ -19,10 +19,11 @@ describe 'extensions' do
19
19
  { 'declared_params' => declared(params) }
20
20
  end
21
21
 
22
+ route_setting :x_operation, some: 'stuff'
23
+
22
24
  desc 'This returns something with extension on verb level',
23
25
  params: Entities::UseResponse.documentation,
24
- failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }],
25
- x: { some: 'stuff' }
26
+ failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
26
27
  params do
27
28
  requires :id, type: Integer
28
29
  end
@@ -57,7 +58,7 @@ describe 'extensions' do
57
58
  { 'declared_params' => declared(params) }
58
59
  end
59
60
 
60
- add_swagger_documentation
61
+ add_swagger_documentation(x: { some: 'stuff' })
61
62
  end
62
63
  end
63
64
  end
@@ -66,6 +67,18 @@ describe 'extensions' do
66
67
  TheApi::ExtensionsApi
67
68
  end
68
69
 
70
+ describe 'extension on root level' do
71
+ subject do
72
+ get '/swagger_doc/path_extension'
73
+ JSON.parse(last_response.body)
74
+ end
75
+
76
+ specify do
77
+ expect(subject).to include 'x-some'
78
+ expect(subject['x-some']).to eql 'stuff'
79
+ end
80
+ end
81
+
69
82
  describe 'extension on path level' do
70
83
  subject do
71
84
  get '/swagger_doc/path_extension'
@@ -56,7 +56,8 @@ describe 'a guarded api endpoint' do
56
56
  class GuardedMountedApi < Grape::API
57
57
  resource_owner_valid = proc { |token_owner = nil| token_owner.nil? }
58
58
 
59
- desc 'Show endpoint if authenticated', hidden: resource_owner_valid
59
+ desc 'Show endpoint if authenticated'
60
+ route_setting :swagger, hidden: resource_owner_valid
60
61
  get '/auth' do
61
62
  { foo: 'bar' }
62
63
  end
@@ -15,6 +15,12 @@ describe 'a hide mounted api' do
15
15
  { foo: 'bar' }
16
16
  end
17
17
 
18
+ desc 'Hide this endpoint using route setting'
19
+ route_setting :swagger, hidden: true
20
+ get '/hide_as_well' do
21
+ { foo: 'bar' }
22
+ end
23
+
18
24
  desc 'Lazily show endpoint', hidden: -> { false }
19
25
  get '/lazy' do
20
26
  { foo: 'bar' }
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: grape-swagger
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.27.1
4
+ version: 0.27.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tim Vandecasteele
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2017-04-28 00:00:00.000000000 Z
11
+ date: 2017-05-11 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: grape
@@ -178,7 +178,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
178
178
  version: '0'
179
179
  requirements: []
180
180
  rubyforge_project:
181
- rubygems_version: 2.6.11
181
+ rubygems_version: 2.6.12
182
182
  signing_key:
183
183
  specification_version: 4
184
184
  summary: Add auto generated documentation to your Grape API that can be displayed