Skip to content

Commit 634d804

Browse files
author
peter scholz
committed
makes param description optional (#399)
1 parent d996138 commit 634d804

20 files changed

+126
-87
lines changed

‎CHANGELOG.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
### next / 2016-xx-xx
2+
3+
#### Features
4+
5+
#### Fixes
6+
7+
* [#399](https://github.com/ruby-grape/grape-swagger/pull/399): makes param description optional, solves [issue #395](https://github.com/ruby-grape/grape-swagger/issues/395) - [@LeFnord](https://github.com/LeFnord).
8+
9+
110
### 0.20.2 / 2016-04-22
211

312
#### Features

‎lib/grape-swagger/doc_methods/operation_id.rb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ module GrapeSwagger
22
module DocMethods
33
class OperationId
44
class << self
5-
def build(method = nil, path = nil)
6-
verb = method.to_s.downcase
5+
def build(route, path = nil)
6+
verb = route.route_method.to_s.downcase
77

88
operation = manipulate(path) unless path.nil?
99

‎lib/grape-swagger/doc_methods/parse_params.rb

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,14 @@ def call(param, settings, route)
1414

1515
value_type = settings.merge(data_type: data_type, path: path, param_name: param, method: method)
1616

17+
# required properties
1718
@parsed_param = {
18-
in: param_type(value_type),
19-
name: settings[:full_name] || param,
20-
description: settings[:desc] || settings[:description] || nil
19+
in: param_type(value_type),
20+
name: settings[:full_name] || param
2121
}
2222

23+
# optional properties
24+
document_description(settings)
2325
document_type_and_format(data_type)
2426
document_array_param(value_type)
2527
document_default_value(settings)
@@ -31,6 +33,11 @@ def call(param, settings, route)
3133

3234
private
3335

36+
def document_description(settings)
37+
description = settings[:desc] || settings[:description]
38+
@parsed_param[:description] = description if description
39+
end
40+
3441
def document_required(settings)
3542
@parsed_param[:required] = settings[:required] || false
3643
@parsed_param[:required] = true if @parsed_param[:in] == 'path'

‎lib/grape-swagger/endpoint.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ def method_object(route, options, path)
110110
method[:parameters] = params_object(route)
111111
method[:responses] = response_object(route, options[:markdown])
112112
method[:tags] = tag_object(route, options[:version])
113-
method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route.route_method, path)
113+
method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
114114
method.delete_if { |_, value| value.blank? }
115115
end
116116

‎spec/lib/extensions_spec.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@
108108
end
109109
end
110110

111-
describe "reale example" do
111+
describe "real example" do
112112
let(:extensions) { {x: {
113113
'amazon-apigateway-auth' => {type: 'none'},
114114
'amazon-apigateway-integration' => {type: 'aws', uri: 'foo_bar_uri', httpMethod: 'get'}

‎spec/lib/operation_id_spec.rb

Lines changed: 41 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,47 @@
77
specify { expect(subject).to respond_to :build }
88

99
describe 'build' do
10-
specify do
11-
expect(subject.build('GET')).to eql 'get'
12-
expect(subject.build('get')).to eql 'get'
13-
expect(subject.build(:get)).to eql 'get'
14-
expect(subject.build('GET', 'foo')).to eql 'getFoo'
15-
expect(subject.build('GET', '/foo')).to eql 'getFoo'
16-
expect(subject.build('GET', 'bar/foo')).to eql 'getBarFoo'
17-
expect(subject.build('GET', 'bar/foo{id}')).to eql 'getBarFooId'
18-
expect(subject.build('GET', '/bar_foo{id}')).to eql 'getBarFooId'
19-
expect(subject.build('GET', '/bar-foo{id}')).to eql 'getBarFooId'
20-
expect(subject.build('GET', '/simple_test/bar-foo{id}')).to eql 'getSimpleTestBarFooId'
10+
let(:route) { Grape::Route.new({ method: method })}
11+
12+
describe 'GET' do
13+
let(:method) { 'GET' }
14+
specify { expect(subject.build(route)).to eql 'get' }
15+
end
16+
describe 'get' do
17+
let(:method) { 'get' }
18+
specify { expect(subject.build(route)).to eql 'get' }
19+
end
20+
describe ':get' do
21+
let(:method) { :get }
22+
specify { expect(subject.build(route)).to eql 'get' }
23+
end
24+
describe 'GET with path foo' do
25+
let(:method) { 'GET' }
26+
specify { expect(subject.build(route, 'foo')).to eql 'getFoo' }
27+
end
28+
describe 'GET with path /foo' do
29+
let(:method) { 'GET' }
30+
specify { expect(subject.build(route, '/foo')).to eql 'getFoo' }
31+
end
32+
describe 'GET with path bar/foo' do
33+
let(:method) { 'GET' }
34+
specify { expect(subject.build(route, 'bar/foo')).to eql 'getBarFoo' }
35+
end
36+
describe 'GET with path bar/foo{id}' do
37+
let(:method) { 'GET' }
38+
specify { expect(subject.build(route, 'bar/foo{id}')).to eql 'getBarFooId' }
39+
end
40+
describe 'GET with path /bar_foo{id}' do
41+
let(:method) { 'GET' }
42+
specify { expect(subject.build(route, '/bar_foo{id}')).to eql 'getBarFooId' }
43+
end
44+
describe 'GET with path /bar-foo{id}' do
45+
let(:method) { 'GET' }
46+
specify { expect(subject.build(route, '/bar-foo{id}')).to eql 'getBarFooId' }
47+
end
48+
describe 'GET with path /simple_test/bar-foo{id}' do
49+
let(:method) { 'GET' }
50+
specify { expect(subject.build(route, '/simple_test/bar-foo{id}')).to eql 'getSimpleTestBarFooId' }
2151
end
2252
end
2353

‎spec/support/api_swagger_v2_result.rb

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -99,8 +99,8 @@ class ApiError < Grape::Entity
9999
"parameters"=>[
100100
{"in"=>"query", "name"=>"id", "description"=>"Identity of Something", "type"=>"integer", "format"=>"int32", "required"=>false},
101101
{"in"=>"query", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>false},
102-
{"in"=>"formData", "name"=>"links", "description"=>nil, "type"=>"array", "items"=>{"type"=>"link"}, "required"=>false},
103-
{"in"=>"query", "name"=>"others", "description"=>nil, "type"=>"text", "required"=>false}
102+
{"in"=>"formData", "name"=>"links", "type"=>"array", "items"=>{"type"=>"link"}, "required"=>false},
103+
{"in"=>"query", "name"=>"others", "type"=>"text", "required"=>false}
104104
],
105105
"responses"=>{"200"=>{"description"=>"This gets Things.", "schema"=>{"$ref"=>"#/definitions/Thing"}}, "401"=>{"description"=>"Unauthorized", "schema"=>{"$ref"=>"#/definitions/ApiError"}}},
106106
"tags"=>["thing"],
@@ -112,7 +112,7 @@ class ApiError < Grape::Entity
112112
"consumes"=>["application/json"],
113113
"parameters"=>[
114114
{"in"=>"formData", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>true},
115-
{"in"=>"formData", "name"=>"links", "description"=>nil, "type"=>"array", "items"=>{"type"=>"string"}, "required"=>true}
115+
{"in"=>"formData", "name"=>"links", "type"=>"array", "items"=>{"type"=>"string"}, "required"=>true}
116116
],
117117
"responses"=>{"201"=>{"description"=>"This creates Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}, "422"=>{"description"=>"Unprocessible Entity"}},
118118
"tags"=>["thing"],
@@ -123,7 +123,7 @@ class ApiError < Grape::Entity
123123
"get"=>{
124124
"description"=>"This gets Thing.",
125125
"produces"=>["application/json"],
126-
"parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}],
126+
"parameters"=>[{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}],
127127
"responses"=>{"200"=>{"description"=>"getting a single thing", "schema"=>{"$ref"=>"#/definitions/Thing"}}, "401"=>{"description"=>"Unauthorized"}},
128128
"tags"=>["thing"],
129129
"operationId"=>"getThingId"
@@ -133,9 +133,9 @@ class ApiError < Grape::Entity
133133
"produces"=>["application/json"],
134134
"consumes"=>["application/json"],
135135
"parameters"=>[
136-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
136+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
137137
{"in"=>"formData", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>false},
138-
{"in"=>"formData", "name"=>"links", "description"=>nil, "type"=>"array", "items"=>{"type"=>"string"}, "required"=>false}
138+
{"in"=>"formData", "name"=>"links", "type"=>"array", "items"=>{"type"=>"string"}, "required"=>false}
139139
],
140140
"responses"=>{"200"=>{"description"=>"This updates Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}},
141141
"tags"=>["thing"],
@@ -144,7 +144,7 @@ class ApiError < Grape::Entity
144144
"delete"=>{
145145
"description"=>"This deletes Thing.",
146146
"produces"=>["application/json"],
147-
"parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}],
147+
"parameters"=>[{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}],
148148
"responses"=>{"200"=>{"description"=>"This deletes Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}},
149149
"tags"=>["thing"],
150150
"operationId"=>"deleteThingId"
@@ -163,7 +163,7 @@ class ApiError < Grape::Entity
163163
"delete"=>{
164164
"description"=>"dummy route.",
165165
"produces"=>["application/json"],
166-
"parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}],
166+
"parameters"=>[{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}],
167167
"responses"=>{"204"=>{"description"=>"dummy route."}, "401"=>{"description"=>"Unauthorized"}},
168168
"tags"=>["dummy"],
169169
"operationId"=>"deleteDummyId"

‎spec/swagger_v2/api_swagger_v2_param_type_body_nested_spec.rb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ def app
117117

118118
specify do
119119
expect(subject['paths']['/simple_nested_params/in_body/{id}']['put']['parameters']).to eql([
120-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
120+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
121121
{
122122
"name"=>"UseNestedWithAddress",
123123
"in"=>"body",
@@ -157,7 +157,7 @@ def app
157157

158158
specify do
159159
expect(subject['paths']['/multiple_nested_params/in_body/{id}']['put']['parameters']).to eql([
160-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
160+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
161161
{"name"=>"UseNestedWithAddress", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddress"}}
162162
])
163163
end

‎spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ def app
9090

9191
specify do
9292
expect(subject['paths']['/wo_entities/in_body/{key}']['put']['parameters']).to eql([
93-
{"in"=>"path", "name"=>"key", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
93+
{"in"=>"path", "name"=>"key", "type"=>"integer", "format"=>"int32", "required"=>true},
9494
{"name"=>"InBody", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestInBody"}}
9595
])
9696
end
@@ -133,7 +133,7 @@ def app
133133

134134
specify do
135135
expect(subject['paths']['/with_entities/in_body/{id}']['put']['parameters']).to eql([
136-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
136+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
137137
{"name"=>"ResponseItem", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestResponseItem"}}
138138
])
139139
end

‎spec/swagger_v2/api_swagger_v2_param_type_spec.rb

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -135,24 +135,24 @@ def app
135135

136136
specify do
137137
expect(subject['paths']['/defined_param_type']['get']['parameters']).to eql([
138-
{"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
139-
{"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
138+
{"in"=>"query", "name"=>"in_query", "required"=>false, "type"=>"string"},
139+
{"in"=>"header", "name"=>"in_header", "required"=>false, "type"=>"string"},
140140
])
141141
end
142142

143143
specify do
144144
expect(subject['paths']['/defined_param_type/{in_path}']['get']['parameters']).to eql([
145-
{"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
146-
{"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
147-
{"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
145+
{"in"=>"path", "name"=>"in_path", "required"=>true, "type"=>"integer", "format"=>"int32"},
146+
{"in"=>"query", "name"=>"in_query", "required"=>false, "type"=>"string"},
147+
{"in"=>"header", "name"=>"in_header", "required"=>false, "type"=>"string"},
148148
])
149149
end
150150

151151
specify do
152152
expect(subject['paths']['/defined_param_type/{in_path}']['delete']['parameters']).to eql([
153-
{"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
154-
{"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
155-
{"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
153+
{"in"=>"path", "name"=>"in_path", "required"=>true, "type"=>"integer", "format"=>"int32"},
154+
{"in"=>"query", "name"=>"in_query", "required"=>false, "type"=>"string"},
155+
{"in"=>"header", "name"=>"in_header", "required"=>false, "type"=>"string"},
156156
])
157157
end
158158
end
@@ -165,24 +165,24 @@ def app
165165

166166
specify do
167167
expect(subject['paths']['/defined_in']['get']['parameters']).to eql([
168-
{"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
169-
{"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
168+
{"in"=>"query", "name"=>"in_query", "required"=>false, "type"=>"string"},
169+
{"in"=>"header", "name"=>"in_header", "required"=>false, "type"=>"string"},
170170
])
171171
end
172172

173173
specify do
174174
expect(subject['paths']['/defined_in/{in_path}']['get']['parameters']).to eql([
175-
{"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
176-
{"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
177-
{"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
175+
{"in"=>"path", "name"=>"in_path", "required"=>true, "type"=>"integer", "format"=>"int32"},
176+
{"in"=>"query", "name"=>"in_query", "required"=>false, "type"=>"string"},
177+
{"in"=>"header", "name"=>"in_header", "required"=>false, "type"=>"string"},
178178
])
179179
end
180180

181181
specify do
182182
expect(subject['paths']['/defined_in/{in_path}']['delete']['parameters']).to eql([
183-
{"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
184-
{"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
185-
{"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
183+
{"in"=>"path", "name"=>"in_path", "required"=>true, "type"=>"integer", "format"=>"int32"},
184+
{"in"=>"query", "name"=>"in_query", "required"=>false, "type"=>"string"},
185+
{"in"=>"header", "name"=>"in_header", "required"=>false, "type"=>"string"},
186186
])
187187
end
188188
end
@@ -196,7 +196,7 @@ def app
196196

197197
specify do
198198
expect(subject['paths']['/upload']['post']['parameters']).to eql([
199-
{"in"=>"formData", "name"=>"name", "description"=>nil, "required"=>true, "type"=>"file"}
199+
{"in"=>"formData", "name"=>"name", "required"=>true, "type"=>"file"}
200200
])
201201
end
202202
end
@@ -209,7 +209,7 @@ def app
209209

210210
specify do
211211
expect(subject['paths']['/download']['get']['parameters']).to eql([
212-
{"in"=>"query", "name"=>"name", "description"=>nil, "required"=>true, "type"=>"string"}
212+
{"in"=>"query", "name"=>"name", "required"=>true, "type"=>"string"}
213213
])
214214
end
215215
end

‎spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,20 +45,20 @@ def app
4545

4646
specify do
4747
expect(subject['paths']['/bookings/{id}']['put']['parameters']).to eql([
48-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
49-
{"in"=>"formData", "name"=>"name", "description"=>nil, "type"=>"string", "required"=>false}
48+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
49+
{"in"=>"formData", "name"=>"name", "type"=>"string", "required"=>false}
5050
])
5151
end
5252

5353
specify do
5454
expect(subject['paths']['/bookings/{id}']['get']['parameters']).to eql([
55-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}
55+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}
5656
])
5757
end
5858

5959
specify do
6060
expect(subject['paths']['/bookings/{id}']['delete']['parameters']).to eql([
61-
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}
61+
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}
6262
])
6363
end
6464
end

‎spec/swagger_v2/api_swagger_v2_response_spec.rb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -155,8 +155,8 @@ def app
155155
"produces"=>["application/json"],
156156
"consumes"=>["application/json"],
157157
"parameters"=>[
158-
{"in"=>"formData", "name"=>"description", "description"=>nil, "type"=>"string", "required"=>false},
159-
{"in"=>"formData", "name"=>"$responses", "description"=>nil, "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
158+
{"in"=>"formData", "name"=>"description", "type"=>"string", "required"=>false},
159+
{"in"=>"formData", "name"=>"$responses", "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
160160
"tags"=>["params_response"],
161161
"operationId"=>"postParamsResponse",
162162
"responses"=>{

0 commit comments

Comments
 (0)