Skip to content

Commit 3057a2c

Browse files
Owen Ben DaviesLeFnord
Owen Ben Davies
authored and
LeFnord
committed
Make route summary optional (#667)
Resolves #661 Currently if no summary is provided, grape-swagger uses the description. This creates needless duplicate fields. As summary is an optional field this changes functionality so summary is only populated if specifically needed. Reference https://swagger.io/specification/
1 parent 6e564a1 commit 3057a2c

12 files changed

+2
-49
lines changed

‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
#### Features
44

5+
* [#667](https://github.com/ruby-grape/grape-swagger/pull/667): Make route summary optional - [@obduk](https://github.com/obduk).
56
* [#670](https://github.com/ruby-grape/grape-swagger/pull/670): Add support for deprecated field - [@ioanatia](https://github.com/ioanatia).
67

78
* Your contribution here.

‎lib/grape-swagger/endpoint.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ def security_object(route)
139139

140140
def summary_object(route)
141141
summary = route.options[:desc] if route.options.key?(:desc)
142-
summary = route.description if route.description.present?
142+
summary = route.description if route.description.present? && route.options.key?(:detail)
143143
summary = route.options[:summary] if route.options.key?(:summary)
144144

145145
summary

‎spec/support/model_parsers/entity_parser.rb

-8
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
207207
'paths' => {
208208
'/v3/other_thing/{elements}' => {
209209
'get' => {
210-
'summary' => 'nested route inside namespace',
211210
'description' => 'nested route inside namespace',
212211
'produces' => ['application/json'],
213212
'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -220,7 +219,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
220219
},
221220
'/thing' => {
222221
'get' => {
223-
'summary' => 'This gets Things.',
224222
'description' => 'This gets Things.',
225223
'produces' => ['application/json'],
226224
'parameters' => [
@@ -234,7 +232,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
234232
'operationId' => 'getThing'
235233
},
236234
'post' => {
237-
'summary' => 'This creates Thing.',
238235
'description' => 'This creates Thing.',
239236
'produces' => ['application/json'],
240237
'consumes' => ['application/json'],
@@ -249,7 +246,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
249246
},
250247
'/thing/{id}' => {
251248
'get' => {
252-
'summary' => 'This gets Thing.',
253249
'description' => 'This gets Thing.',
254250
'produces' => ['application/json'],
255251
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -258,7 +254,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
258254
'operationId' => 'getThingId'
259255
},
260256
'put' => {
261-
'summary' => 'This updates Thing.',
262257
'description' => 'This updates Thing.',
263258
'produces' => ['application/json'],
264259
'consumes' => ['application/json'],
@@ -272,7 +267,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
272267
'operationId' => 'putThingId'
273268
},
274269
'delete' => {
275-
'summary' => 'This deletes Thing.',
276270
'description' => 'This deletes Thing.',
277271
'produces' => ['application/json'],
278272
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -283,7 +277,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
283277
},
284278
'/thing2' => {
285279
'get' => {
286-
'summary' => 'This gets Things.',
287280
'description' => 'This gets Things.',
288281
'produces' => ['application/json'],
289282
'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -293,7 +286,6 @@ class DocumentedHashAndArrayModel < Grape::Entity
293286
},
294287
'/dummy/{id}' => {
295288
'delete' => {
296-
'summary' => 'dummy route.',
297289
'description' => 'dummy route.',
298290
'produces' => ['application/json'],
299291
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

‎spec/support/model_parsers/mock_parser.rb

-8
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,6 @@ class ApiResponse < OpenStruct; end
199199
'paths' => {
200200
'/v3/other_thing/{elements}' => {
201201
'get' => {
202-
'summary' => 'nested route inside namespace',
203202
'description' => 'nested route inside namespace',
204203
'produces' => ['application/json'],
205204
'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -212,7 +211,6 @@ class ApiResponse < OpenStruct; end
212211
},
213212
'/thing' => {
214213
'get' => {
215-
'summary' => 'This gets Things.',
216214
'description' => 'This gets Things.',
217215
'produces' => ['application/json'],
218216
'parameters' => [
@@ -226,7 +224,6 @@ class ApiResponse < OpenStruct; end
226224
'operationId' => 'getThing'
227225
},
228226
'post' => {
229-
'summary' => 'This creates Thing.',
230227
'description' => 'This creates Thing.',
231228
'produces' => ['application/json'],
232229
'consumes' => ['application/json'],
@@ -241,7 +238,6 @@ class ApiResponse < OpenStruct; end
241238
},
242239
'/thing/{id}' => {
243240
'get' => {
244-
'summary' => 'This gets Thing.',
245241
'description' => 'This gets Thing.',
246242
'produces' => ['application/json'],
247243
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -250,7 +246,6 @@ class ApiResponse < OpenStruct; end
250246
'operationId' => 'getThingId'
251247
},
252248
'put' => {
253-
'summary' => 'This updates Thing.',
254249
'description' => 'This updates Thing.',
255250
'produces' => ['application/json'],
256251
'consumes' => ['application/json'],
@@ -264,7 +259,6 @@ class ApiResponse < OpenStruct; end
264259
'operationId' => 'putThingId'
265260
},
266261
'delete' => {
267-
'summary' => 'This deletes Thing.',
268262
'description' => 'This deletes Thing.',
269263
'produces' => ['application/json'],
270264
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -275,7 +269,6 @@ class ApiResponse < OpenStruct; end
275269
},
276270
'/thing2' => {
277271
'get' => {
278-
'summary' => 'This gets Things.',
279272
'description' => 'This gets Things.',
280273
'produces' => ['application/json'],
281274
'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -285,7 +278,6 @@ class ApiResponse < OpenStruct; end
285278
},
286279
'/dummy/{id}' => {
287280
'delete' => {
288-
'summary' => 'dummy route.',
289281
'description' => 'dummy route.',
290282
'produces' => ['application/json'],
291283
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

‎spec/support/model_parsers/representable_parser.rb

-8
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
279279
'paths' => {
280280
'/v3/other_thing/{elements}' => {
281281
'get' => {
282-
'summary' => 'nested route inside namespace',
283282
'description' => 'nested route inside namespace',
284283
'produces' => ['application/json'],
285284
'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -292,7 +291,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
292291
},
293292
'/thing' => {
294293
'get' => {
295-
'summary' => 'This gets Things.',
296294
'description' => 'This gets Things.',
297295
'produces' => ['application/json'],
298296
'parameters' => [
@@ -306,7 +304,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
306304
'operationId' => 'getThing'
307305
},
308306
'post' => {
309-
'summary' => 'This creates Thing.',
310307
'description' => 'This creates Thing.',
311308
'produces' => ['application/json'],
312309
'consumes' => ['application/json'],
@@ -321,7 +318,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
321318
},
322319
'/thing/{id}' => {
323320
'get' => {
324-
'summary' => 'This gets Thing.',
325321
'description' => 'This gets Thing.',
326322
'produces' => ['application/json'],
327323
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -330,7 +326,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
330326
'operationId' => 'getThingId'
331327
},
332328
'put' => {
333-
'summary' => 'This updates Thing.',
334329
'description' => 'This updates Thing.',
335330
'produces' => ['application/json'],
336331
'consumes' => ['application/json'],
@@ -344,7 +339,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
344339
'operationId' => 'putThingId'
345340
},
346341
'delete' => {
347-
'summary' => 'This deletes Thing.',
348342
'description' => 'This deletes Thing.',
349343
'produces' => ['application/json'],
350344
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -355,7 +349,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
355349
},
356350
'/thing2' => {
357351
'get' => {
358-
'summary' => 'This gets Things.',
359352
'description' => 'This gets Things.',
360353
'produces' => ['application/json'],
361354
'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -365,7 +358,6 @@ class DocumentedHashAndArrayModel < Representable::Decorator
365358
},
366359
'/dummy/{id}' => {
367360
'delete' => {
368-
'summary' => 'dummy route.',
369361
'description' => 'dummy route.',
370362
'produces' => ['application/json'],
371363
'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

‎spec/swagger_v2/api_swagger_v2_response_spec.rb

-3
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@ def app
4747
end
4848
specify do
4949
expect(subject['paths']['/nested_type']['get']).to eql(
50-
'summary' => 'This returns something',
5150
'description' => 'This returns something',
5251
'produces' => ['application/json'],
5352
'responses' => {
@@ -69,7 +68,6 @@ def app
6968

7069
specify do
7170
expect(subject['paths']['/entity_response']['get']).to eql(
72-
'summary' => 'This returns something',
7371
'description' => 'This returns something',
7472
'produces' => ['application/json'],
7573
'responses' => {
@@ -91,7 +89,6 @@ def app
9189

9290
specify do
9391
expect(subject['paths']['/params_given']['post']).to eql(
94-
'summary' => 'This returns something',
9592
'description' => 'This returns something',
9693
'produces' => ['application/json'],
9794
'consumes' => ['application/json'],

‎spec/swagger_v2/default_api_spec.rb

-2
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@ def app
3131
'paths' => {
3232
'/something' => {
3333
'get' => {
34-
'summary' => 'This gets something.',
3534
'description' => 'This gets something.',
3635
'produces' => ['application/json'],
3736
'tags' => ['something'],
@@ -78,7 +77,6 @@ def app
7877
'paths' => {
7978
'/something' => {
8079
'get' => {
81-
'summary' => 'This gets something.',
8280
'description' => 'This gets something.',
8381
'produces' => ['application/json'],
8482
'tags' => ['something'],

‎spec/swagger_v2/guarded_endpoint_spec.rb

-1
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,6 @@ def app
8383
'paths' => {
8484
'/auth' => {
8585
'get' => {
86-
'summary' => 'Show endpoint if authenticated',
8786
'description' => 'Show endpoint if authenticated',
8887
'produces' => ['application/json'],
8988
'tags' => ['auth'],

‎spec/swagger_v2/hide_api_spec.rb

-4
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,6 @@ def app
5252
'paths' => {
5353
'/simple' => {
5454
'get' => {
55-
'summary' => 'Show this endpoint',
5655
'description' => 'Show this endpoint',
5756
'produces' => ['application/json'],
5857
'tags' => ['simple'],
@@ -62,7 +61,6 @@ def app
6261
},
6362
'/lazy' => {
6463
'get' => {
65-
'summary' => 'Lazily show endpoint',
6664
'description' => 'Lazily show endpoint',
6765
'produces' => ['application/json'],
6866
'tags' => ['lazy'],
@@ -115,7 +113,6 @@ def app
115113
'paths' => {
116114
'/simple/show' => {
117115
'get' => {
118-
'summary' => 'Show this endpoint',
119116
'description' => 'Show this endpoint',
120117
'produces' => ['application/json'],
121118
'operationId' => 'getSimpleShow',
@@ -137,7 +134,6 @@ def app
137134
'paths' => {
138135
'/simple/show' => {
139136
'get' => {
140-
'summary' => 'Show this endpoint',
141137
'description' => 'Show this endpoint',
142138
'produces' => ['application/json'],
143139
'tags' => ['simple'],

‎spec/swagger_v2/mount_override_api_spec.rb

-1
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,6 @@ def app
5050
end
5151

5252
it 'shows documentation from new endpoint' do
53-
expect(subject['summary']).to eql('new endpoint')
5453
expect(subject['parameters'][0]['description']).to eql('new param')
5554
expect(subject['parameters'][0]['type']).to eql('string')
5655
expect(subject['responses']['200']['description']).to eql('new message')

‎spec/swagger_v2/mounted_target_class_spec.rb

-2
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,6 @@ def app
3939
'paths' => {
4040
'/simple' => {
4141
'get' => {
42-
'summary' => 'This gets something.',
4342
'description' => 'This gets something.',
4443
'produces' => ['application/json'],
4544
'responses' => { '200' => { 'description' => 'This gets something.' } },
@@ -62,7 +61,6 @@ def app
6261
'paths' => {
6362
'/simple' => {
6463
'get' => {
65-
'summary' => 'This gets something.',
6664
'description' => 'This gets something.',
6765
'produces' => ['application/json'],
6866
'responses' => {

0 commit comments

Comments
 (0)