Skip to content

makes param description optional #399

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 24, 2016
Merged

makes param description optional #399

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
### next / 2016-xx-xx

#### Features

#### Fixes

* [#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).


### 0.20.2 / 2016-04-22

#### Features
Expand Down
4 changes: 2 additions & 2 deletions lib/grape-swagger/doc_methods/operation_id.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ module GrapeSwagger
module DocMethods
class OperationId
class << self
def build(method = nil, path = nil)
verb = method.to_s.downcase
def build(route, path = nil)
verb = route.route_method.to_s.downcase

operation = manipulate(path) unless path.nil?

Expand Down
13 changes: 10 additions & 3 deletions lib/grape-swagger/doc_methods/parse_params.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ def call(param, settings, route)

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

# required properties
@parsed_param = {
in: param_type(value_type),
name: settings[:full_name] || param,
description: settings[:desc] || settings[:description] || nil
in: param_type(value_type),
name: settings[:full_name] || param
}

# optional properties
document_description(settings)
document_type_and_format(data_type)
document_array_param(value_type)
document_default_value(settings)
Expand All @@ -31,6 +33,11 @@ def call(param, settings, route)

private

def document_description(settings)
description = settings[:desc] || settings[:description]
@parsed_param[:description] = description if description
end

def document_required(settings)
@parsed_param[:required] = settings[:required] || false
@parsed_param[:required] = true if @parsed_param[:in] == 'path'
Expand Down
2 changes: 1 addition & 1 deletion lib/grape-swagger/endpoint.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ def method_object(route, options, path)
method[:parameters] = params_object(route)
method[:responses] = response_object(route, options[:markdown])
method[:tags] = tag_object(route, options[:version])
method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route.route_method, path)
method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
method.delete_if { |_, value| value.blank? }
end

Expand Down
2 changes: 1 addition & 1 deletion spec/lib/extensions_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@
end
end

describe "reale example" do
describe "real example" do
let(:extensions) { {x: {
'amazon-apigateway-auth' => {type: 'none'},
'amazon-apigateway-integration' => {type: 'aws', uri: 'foo_bar_uri', httpMethod: 'get'}
Expand Down
52 changes: 41 additions & 11 deletions spec/lib/operation_id_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,47 @@
specify { expect(subject).to respond_to :build }

describe 'build' do
specify do
expect(subject.build('GET')).to eql 'get'
expect(subject.build('get')).to eql 'get'
expect(subject.build(:get)).to eql 'get'
expect(subject.build('GET', 'foo')).to eql 'getFoo'
expect(subject.build('GET', '/foo')).to eql 'getFoo'
expect(subject.build('GET', 'bar/foo')).to eql 'getBarFoo'
expect(subject.build('GET', 'bar/foo{id}')).to eql 'getBarFooId'
expect(subject.build('GET', '/bar_foo{id}')).to eql 'getBarFooId'
expect(subject.build('GET', '/bar-foo{id}')).to eql 'getBarFooId'
expect(subject.build('GET', '/simple_test/bar-foo{id}')).to eql 'getSimpleTestBarFooId'
let(:route) { Grape::Route.new({ method: method })}

describe 'GET' do
let(:method) { 'GET' }
specify { expect(subject.build(route)).to eql 'get' }
end
describe 'get' do
let(:method) { 'get' }
specify { expect(subject.build(route)).to eql 'get' }
end
describe ':get' do
let(:method) { :get }
specify { expect(subject.build(route)).to eql 'get' }
end
describe 'GET with path foo' do
let(:method) { 'GET' }
specify { expect(subject.build(route, 'foo')).to eql 'getFoo' }
end
describe 'GET with path /foo' do
let(:method) { 'GET' }
specify { expect(subject.build(route, '/foo')).to eql 'getFoo' }
end
describe 'GET with path bar/foo' do
let(:method) { 'GET' }
specify { expect(subject.build(route, 'bar/foo')).to eql 'getBarFoo' }
end
describe 'GET with path bar/foo{id}' do
let(:method) { 'GET' }
specify { expect(subject.build(route, 'bar/foo{id}')).to eql 'getBarFooId' }
end
describe 'GET with path /bar_foo{id}' do
let(:method) { 'GET' }
specify { expect(subject.build(route, '/bar_foo{id}')).to eql 'getBarFooId' }
end
describe 'GET with path /bar-foo{id}' do
let(:method) { 'GET' }
specify { expect(subject.build(route, '/bar-foo{id}')).to eql 'getBarFooId' }
end
describe 'GET with path /simple_test/bar-foo{id}' do
let(:method) { 'GET' }
specify { expect(subject.build(route, '/simple_test/bar-foo{id}')).to eql 'getSimpleTestBarFooId' }
end
end

Expand Down
16 changes: 8 additions & 8 deletions spec/support/api_swagger_v2_result.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,8 +99,8 @@ class ApiError < Grape::Entity
"parameters"=>[
{"in"=>"query", "name"=>"id", "description"=>"Identity of Something", "type"=>"integer", "format"=>"int32", "required"=>false},
{"in"=>"query", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>false},
{"in"=>"formData", "name"=>"links", "description"=>nil, "type"=>"array", "items"=>{"type"=>"link"}, "required"=>false},
{"in"=>"query", "name"=>"others", "description"=>nil, "type"=>"text", "required"=>false}
{"in"=>"formData", "name"=>"links", "type"=>"array", "items"=>{"type"=>"link"}, "required"=>false},
{"in"=>"query", "name"=>"others", "type"=>"text", "required"=>false}
],
"responses"=>{"200"=>{"description"=>"This gets Things.", "schema"=>{"$ref"=>"#/definitions/Thing"}}, "401"=>{"description"=>"Unauthorized", "schema"=>{"$ref"=>"#/definitions/ApiError"}}},
"tags"=>["thing"],
Expand All @@ -112,7 +112,7 @@ class ApiError < Grape::Entity
"consumes"=>["application/json"],
"parameters"=>[
{"in"=>"formData", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>true},
{"in"=>"formData", "name"=>"links", "description"=>nil, "type"=>"array", "items"=>{"type"=>"string"}, "required"=>true}
{"in"=>"formData", "name"=>"links", "type"=>"array", "items"=>{"type"=>"string"}, "required"=>true}
],
"responses"=>{"201"=>{"description"=>"This creates Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}, "422"=>{"description"=>"Unprocessible Entity"}},
"tags"=>["thing"],
Expand All @@ -123,7 +123,7 @@ class ApiError < Grape::Entity
"get"=>{
"description"=>"This gets Thing.",
"produces"=>["application/json"],
"parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}],
"parameters"=>[{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}],
"responses"=>{"200"=>{"description"=>"getting a single thing", "schema"=>{"$ref"=>"#/definitions/Thing"}}, "401"=>{"description"=>"Unauthorized"}},
"tags"=>["thing"],
"operationId"=>"getThingId"
Expand All @@ -133,9 +133,9 @@ class ApiError < Grape::Entity
"produces"=>["application/json"],
"consumes"=>["application/json"],
"parameters"=>[
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
{"in"=>"formData", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>false},
{"in"=>"formData", "name"=>"links", "description"=>nil, "type"=>"array", "items"=>{"type"=>"string"}, "required"=>false}
{"in"=>"formData", "name"=>"links", "type"=>"array", "items"=>{"type"=>"string"}, "required"=>false}
],
"responses"=>{"200"=>{"description"=>"This updates Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}},
"tags"=>["thing"],
Expand All @@ -144,7 +144,7 @@ class ApiError < Grape::Entity
"delete"=>{
"description"=>"This deletes Thing.",
"produces"=>["application/json"],
"parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}],
"parameters"=>[{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}],
"responses"=>{"200"=>{"description"=>"This deletes Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}},
"tags"=>["thing"],
"operationId"=>"deleteThingId"
Expand All @@ -163,7 +163,7 @@ class ApiError < Grape::Entity
"delete"=>{
"description"=>"dummy route.",
"produces"=>["application/json"],
"parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}],
"parameters"=>[{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}],
"responses"=>{"204"=>{"description"=>"dummy route."}, "401"=>{"description"=>"Unauthorized"}},
"tags"=>["dummy"],
"operationId"=>"deleteDummyId"
Expand Down
4 changes: 2 additions & 2 deletions spec/swagger_v2/api_swagger_v2_param_type_body_nested_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ def app

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

specify do
expect(subject['paths']['/multiple_nested_params/in_body/{id}']['put']['parameters']).to eql([
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
{"name"=>"UseNestedWithAddress", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddress"}}
])
end
Expand Down
4 changes: 2 additions & 2 deletions spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ def app

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

specify do
expect(subject['paths']['/with_entities/in_body/{id}']['put']['parameters']).to eql([
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true},
{"name"=>"ResponseItem", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestResponseItem"}}
])
end
Expand Down
36 changes: 18 additions & 18 deletions spec/swagger_v2/api_swagger_v2_param_type_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,24 +135,24 @@ def app

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

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

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

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

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

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

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

specify do
expect(subject['paths']['/download']['get']['parameters']).to eql([
{"in"=>"query", "name"=>"name", "description"=>nil, "required"=>true, "type"=>"string"}
{"in"=>"query", "name"=>"name", "required"=>true, "type"=>"string"}
])
end
end
Expand Down
8 changes: 4 additions & 4 deletions spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,20 +45,20 @@ def app

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

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

specify do
expect(subject['paths']['/bookings/{id}']['delete']['parameters']).to eql([
{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}
{"in"=>"path", "name"=>"id", "type"=>"integer", "format"=>"int32", "required"=>true}
])
end
end
4 changes: 2 additions & 2 deletions spec/swagger_v2/api_swagger_v2_response_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,8 +155,8 @@ def app
"produces"=>["application/json"],
"consumes"=>["application/json"],
"parameters"=>[
{"in"=>"formData", "name"=>"description", "description"=>nil, "type"=>"string", "required"=>false},
{"in"=>"formData", "name"=>"$responses", "description"=>nil, "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
{"in"=>"formData", "name"=>"description", "type"=>"string", "required"=>false},
{"in"=>"formData", "name"=>"$responses", "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
"tags"=>["params_response"],
"operationId"=>"postParamsResponse",
"responses"=>{
Expand Down
Loading