Skip to content

Commit a828ce0

Browse files
BhacazBhacaz
committed
Don't overwrite model description with the route destription.
1 parent 588579d commit a828ce0

File tree

7 files changed

+89
-33
lines changed

7 files changed

+89
-33
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
#### Fixes
88

99
* Your contribution here.
10-
10+
* [#804](https://github.com/ruby-grape/grape-swagger/pull/804): Don't overwrite model description with the route description. - [@Bhacaz](https://github.com/Bhacaz)
1111

1212
### 1.2.1 (July 15, 2020)
1313

‎lib/grape-swagger/endpoint.rb

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -78,11 +78,11 @@ def contact_object(infos)
7878
def path_and_definition_objects(namespace_routes, options)
7979
@paths = {}
8080
@definitions = {}
81+
add_definitions_from options[:models]
8182
namespace_routes.each_value do |routes|
8283
path_item(routes, options)
8384
end
8485

85-
add_definitions_from options[:models]
8686
[@paths, @definitions]
8787
end
8888

@@ -207,19 +207,22 @@ def response_object(route, options)
207207

208208
next build_file_response(memo[value[:code]]) if file_response?(value[:model])
209209

210-
response_model = @item
211-
response_model = expose_params_from_model(value[:model]) if value[:model]
212-
213210
if memo.key?(200) && route.request_method == 'DELETE' && value[:model].nil?
214211
memo[204] = memo.delete(200)
215212
value[:code] = 204
216213
end
217214

218215
next if value[:code] == 204
219-
next unless !response_model.start_with?('Swagger_doc') && (@definitions[response_model] || value[:model])
216+
# Explicitly request no model with { model: '' }
217+
next if value[:model] == ''
218+
219+
response_model = @item
220+
response_model = expose_params_from_model(value[:model]) if value[:model]
220221

221-
@definitions[response_model][:description] = description_object(route)
222+
next unless @definitions[response_model]
223+
next if response_model.start_with?('Swagger_doc')
222224

225+
@definitions[response_model][:description] ||= "#{response_model} model"
223226
memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
224227
memo[value[:code]][:examples] = value[:examples] if value[:examples]
225228
end

‎spec/support/model_parsers/entity_parser.rb

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -145,23 +145,23 @@ class DocumentedHashAndArrayModel < Grape::Entity
145145

146146
let(:swagger_nested_type) do
147147
{
148-
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } }, 'description' => 'This returns something' },
148+
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } }, 'description' => 'ApiError model' },
149149
'ResponseItem' => { 'type' => 'object', 'properties' => { 'id' => { 'type' => 'integer', 'format' => 'int32' }, 'name' => { 'type' => 'string' } } },
150-
'UseItemResponseAsType' => { 'type' => 'object', 'properties' => { 'description' => { 'type' => 'string' }, 'responses' => { '$ref' => '#/definitions/ResponseItem' } }, 'description' => 'This returns something' }
150+
'UseItemResponseAsType' => { 'type' => 'object', 'properties' => { 'description' => { 'type' => 'string' }, 'responses' => { '$ref' => '#/definitions/ResponseItem' } }, 'description' => 'UseItemResponseAsType model' }
151151
}
152152
end
153153

154154
let(:swagger_entity_as_response_object) do
155155
{
156-
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } }, 'description' => 'This returns something' },
156+
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } }, 'description' => 'ApiError model' },
157157
'ResponseItem' => { 'type' => 'object', 'properties' => { 'id' => { 'type' => 'integer', 'format' => 'int32' }, 'name' => { 'type' => 'string' } } },
158-
'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' } } }, 'description' => 'This returns something' }
158+
'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' } } }, 'description' => 'UseResponse model' }
159159
}
160160
end
161161

162162
let(:swagger_params_as_response_object) do
163163
{
164-
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' }
164+
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' }
165165
}
166166
end
167167

@@ -300,7 +300,7 @@ class DocumentedHashAndArrayModel < Grape::Entity
300300
'type' => 'object',
301301
'required' => ['elements'],
302302
'properties' => { 'elements' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/QueryInputElement' }, 'description' => 'Set of configuration' } },
303-
'description' => 'nested route inside namespace'
303+
'description' => 'QueryInput model'
304304
},
305305
'QueryInputElement' => {
306306
'type' => 'object',
@@ -310,7 +310,7 @@ class DocumentedHashAndArrayModel < Grape::Entity
310310
'ApiError' => {
311311
'type' => 'object',
312312
'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } },
313-
'description' => 'This gets Things.'
313+
'description' => 'ApiError model'
314314
},
315315
'Something' => {
316316
'type' => 'object',
@@ -320,7 +320,7 @@ class DocumentedHashAndArrayModel < Grape::Entity
320320
'links' => { 'type' => 'array', 'items' => { 'type' => 'link' } },
321321
'others' => { 'type' => 'text' }
322322
},
323-
'description' => 'This gets Things.'
323+
'description' => 'Something model'
324324
}
325325
}
326326
}

‎spec/support/model_parsers/mock_parser.rb

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ class ApiResponse < OpenStruct; end
112112
'description' => "it's a mock"
113113
}
114114
},
115-
'description' => 'This returns something'
115+
'description' => 'ApiError model'
116116
},
117117
'UseItemResponseAsType' => {
118118
'type' => 'object',
@@ -122,7 +122,7 @@ class ApiResponse < OpenStruct; end
122122
'description' => "it's a mock"
123123
}
124124
},
125-
'description' => 'This returns something'
125+
'description' => 'UseItemResponseAsType model'
126126
}
127127
}
128128
end
@@ -137,7 +137,7 @@ class ApiResponse < OpenStruct; end
137137
'description' => "it's a mock"
138138
}
139139
},
140-
'description' => 'This returns something'
140+
'description' => 'UseResponse model'
141141
},
142142
'ApiError' => {
143143
'type' => 'object',
@@ -147,7 +147,7 @@ class ApiResponse < OpenStruct; end
147147
'description' => "it's a mock"
148148
}
149149
},
150-
'description' => 'This returns something'
150+
'description' => 'ApiError model'
151151
}
152152
}
153153
end
@@ -162,7 +162,7 @@ class ApiResponse < OpenStruct; end
162162
'description' => "it's a mock"
163163
}
164164
},
165-
'description' => 'This returns something'
165+
'description' => 'ApiError model'
166166
}
167167
}
168168
end
@@ -296,7 +296,7 @@ class ApiResponse < OpenStruct; end
296296
'description' => "it's a mock"
297297
}
298298
},
299-
'description' => 'nested route inside namespace'
299+
'description' => 'QueryInput model'
300300
},
301301
'ApiError' => {
302302
'type' => 'object',
@@ -306,7 +306,7 @@ class ApiResponse < OpenStruct; end
306306
'description' => "it's a mock"
307307
}
308308
},
309-
'description' => 'This gets Things.'
309+
'description' => 'ApiError model'
310310
},
311311
'Something' => {
312312
'type' => 'object',
@@ -316,7 +316,7 @@ class ApiResponse < OpenStruct; end
316316
'description' => "it's a mock"
317317
}
318318
},
319-
'description' => 'This gets Things.'
319+
'description' => 'Something model'
320320
}
321321
}
322322
}

‎spec/support/model_parsers/representable_parser.rb

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -218,22 +218,22 @@ class DocumentedHashAndArrayModel < Representable::Decorator
218218

219219
let(:swagger_nested_type) do
220220
{
221-
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' },
222-
'UseItemResponseAsType' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, 'responses' => { 'description' => '', 'type' => 'ResponseItem' } }, 'description' => 'This returns something' }
221+
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' },
222+
'UseItemResponseAsType' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, 'responses' => { 'description' => '', 'type' => 'ResponseItem' } }, 'description' => 'UseItemResponseAsType model' }
223223
}
224224
end
225225

226226
let(:swagger_entity_as_response_object) do
227227
{
228-
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' },
228+
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' },
229229
'ResponseItem' => { 'type' => 'object', 'properties' => { 'id' => { 'description' => '', 'type' => 'integer', 'format' => 'int32' }, 'name' => { 'description' => '', 'type' => 'string' } } },
230-
'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } }, 'description' => 'This returns something' }
230+
'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } }, 'description' => 'UseResponse model' }
231231
}
232232
end
233233

234234
let(:swagger_params_as_response_object) do
235235
{
236-
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' }
236+
'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'ApiError model' }
237237
}
238238
end
239239

@@ -372,7 +372,7 @@ class DocumentedHashAndArrayModel < Representable::Decorator
372372
'type' => 'object',
373373
'required' => ['elements'],
374374
'properties' => { 'elements' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/QueryInputElement' }, 'description' => 'Set of configuration' } },
375-
'description' => 'nested route inside namespace'
375+
'description' => 'QueryInput model'
376376
},
377377
'QueryInputElement' => {
378378
'type' => 'object',
@@ -382,7 +382,7 @@ class DocumentedHashAndArrayModel < Representable::Decorator
382382
'ApiError' => {
383383
'type' => 'object',
384384
'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } },
385-
'description' => 'This gets Things.'
385+
'description' => 'ApiError model'
386386
},
387387
'Something' => {
388388
'type' => 'object',
@@ -392,7 +392,7 @@ class DocumentedHashAndArrayModel < Representable::Decorator
392392
'links' => { 'type' => 'array', 'items' => { 'description' => '', 'type' => 'link' } },
393393
'others' => { 'description' => '', 'type' => 'text' }
394394
},
395-
'description' => 'This gets Things.'
395+
'description' => 'Something model'
396396
}
397397
}
398398
}

‎spec/swagger_v2/api_swagger_v2_response_with_models_spec.rb

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# frozen_string_literal: true
2+
3+
require 'spec_helper'
4+
5+
describe 'response' do
6+
include_context "#{MODEL_PARSER} swagger example"
7+
8+
before :all do
9+
module TheApi
10+
class ResponseApiModels < Grape::API
11+
format :json
12+
13+
desc 'This returns something',
14+
success: [{ code: 200 }],
15+
failure: [
16+
{ code: 400, message: 'NotFound', model: '' },
17+
{ code: 404, message: 'BadRequest', model: Entities::ApiError }
18+
]
19+
get '/use-response' do
20+
{ 'declared_params' => declared(params) }
21+
end
22+
23+
add_swagger_documentation(models: [Entities::UseResponse])
24+
end
25+
end
26+
end
27+
28+
def app
29+
TheApi::ResponseApiModels
30+
end
31+
32+
describe 'uses entity as response object implicitly with route name' do
33+
subject do
34+
get '/swagger_doc/use-response'
35+
JSON.parse(last_response.body)
36+
end
37+
38+
specify do
39+
expect(subject['paths']['/use-response']['get']).to eql(
40+
'description' => 'This returns something',
41+
'produces' => ['application/json'],
42+
'responses' => {
43+
'200' => { 'description' => 'This returns something', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
44+
'400' => { 'description' => 'NotFound' },
45+
'404' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' } }
46+
},
47+
'tags' => ['use-response'],
48+
'operationId' => 'getUseResponse'
49+
)
50+
expect(subject['definitions']).to eql(swagger_entity_as_response_object)
51+
end
52+
end
53+
end

‎spec/swagger_v2/reference_entity_spec.rb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ def app
103103
'description' => 'Something interesting.'
104104
}
105105
},
106-
'description' => 'This returns kind and something or an error'
106+
'description' => 'KindCustom model'
107107
)
108108
end
109109
end
@@ -122,7 +122,7 @@ def app
122122
'title' => { 'type' => 'string', 'description' => 'Title of the parent.' },
123123
'child' => { 'type' => 'string', 'description' => 'Child property.' }
124124
},
125-
'description' => 'This returns a child entity'
125+
'description' => 'MyAPI::Child model'
126126
)
127127
end
128128
end

0 commit comments

Comments
 (0)