makes param description optional

CHANGELOG.md

@@ -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

lib/grape-swagger/doc_methods/operation_id.rb

@@ -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?
 

lib/grape-swagger/doc_methods/parse_params.rb

@@ -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)
@@ -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'

lib/grape-swagger/endpoint.rb

@@ -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
 

spec/lib/extensions_spec.rb

@@ -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'}

spec/lib/operation_id_spec.rb

@@ -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
 

spec/support/api_swagger_v2_result.rb

@@ -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"],
@@ -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"],
@@ -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"
@@ -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"],
@@ -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"
@@ -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"

spec/swagger_v2/api_swagger_v2_param_type_body_nested_spec.rb

@@ -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",
@@ -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

spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb

@@ -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
@@ -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

spec/swagger_v2/api_swagger_v2_param_type_spec.rb

@@ -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
@@ -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
@@ -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
@@ -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

spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb

@@ -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

spec/swagger_v2/api_swagger_v2_response_spec.rb

@@ -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"=>{