makes param description optional

Author: Peter Scholz

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/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'

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

spec/swagger_v2/api_swagger_v2_type-format_spec.rb

@@ -83,20 +83,20 @@ def app
 
   specify do
     expect(subject['paths']['/request_types']['post']['parameters']).to eql([
-      {"in"=>"formData", "name"=>"param_integer", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
-      {"in"=>"formData", "name"=>"param_long", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int64"},
-      {"in"=>"formData", "name"=>"param_float", "description"=>nil, "required"=>true, "type"=>"number", "format"=>"float"},
-      {"in"=>"formData", "name"=>"param_double", "description"=>nil, "required"=>true, "type"=>"number", "format"=>"double"},
-      {"in"=>"formData", "name"=>"param_string", "description"=>nil, "required"=>false, "type"=>"string"},
-      {"in"=>"formData", "name"=>"param_symbol", "description"=>nil, "required"=>false, "type"=>"string"},
-      {"in"=>"formData", "name"=>"param_date", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"date"},
-      {"in"=>"formData", "name"=>"param_date_time", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"date-time"},
-      {"in"=>"formData", "name"=>"param_time", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"date-time"},
-      {"in"=>"formData", "name"=>"param_password", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"password"},
-      {"in"=>"formData", "name"=>"param_email", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"email"},
-      {"in"=>"formData", "name"=>"param_boolean", "description"=>nil, "required"=>false, "type"=>"boolean"},
-      {"in"=>"formData", "name"=>"param_file", "description"=>nil, "required"=>false, "type"=>"file"},
-      {"in"=>"formData", "name"=>"param_json", "description"=>nil, "required"=>false, "type"=>"json"}
+      {"in"=>"formData", "name"=>"param_integer", "required"=>true, "type"=>"integer", "format"=>"int32"},
+      {"in"=>"formData", "name"=>"param_long", "required"=>true, "type"=>"integer", "format"=>"int64"},
+      {"in"=>"formData", "name"=>"param_float", "required"=>true, "type"=>"number", "format"=>"float"},
+      {"in"=>"formData", "name"=>"param_double", "required"=>true, "type"=>"number", "format"=>"double"},
+      {"in"=>"formData", "name"=>"param_string", "required"=>false, "type"=>"string"},
+      {"in"=>"formData", "name"=>"param_symbol", "required"=>false, "type"=>"string"},
+      {"in"=>"formData", "name"=>"param_date", "required"=>true, "type"=>"string", "format"=>"date"},
+      {"in"=>"formData", "name"=>"param_date_time", "required"=>true, "type"=>"string", "format"=>"date-time"},
+      {"in"=>"formData", "name"=>"param_time", "required"=>true, "type"=>"string", "format"=>"date-time"},
+      {"in"=>"formData", "name"=>"param_password", "required"=>true, "type"=>"string", "format"=>"password"},
+      {"in"=>"formData", "name"=>"param_email", "required"=>true, "type"=>"string", "format"=>"email"},
+      {"in"=>"formData", "name"=>"param_boolean", "required"=>false, "type"=>"boolean"},
+      {"in"=>"formData", "name"=>"param_file", "required"=>false, "type"=>"file"},
+      {"in"=>"formData", "name"=>"param_json", "required"=>false, "type"=>"json"}
     ])
   end
 

spec/swagger_v2/boolean_params_spec.rb

@@ -24,7 +24,7 @@ def app
 
   it 'converts boolean types' do
     expect(subject).to eq [
-      {"in"=>"formData", "name"=>"a_boolean", "description"=>nil, "type"=>"boolean", "required"=>true}
+      {"in"=>"formData", "name"=>"a_boolean", "type"=>"boolean", "required"=>true}
     ]
   end
 end

spec/swagger_v2/float_api_spec.rb

@@ -24,7 +24,7 @@ def app
 
   it 'converts float types' do
     expect(subject).to eq [
-      {"in"=>"formData", "name"=>"a_float", "description"=>nil, "type"=>"number", "required"=>true, "format"=>"float"}
+      {"in"=>"formData", "name"=>"a_float", "type"=>"number", "required"=>true, "format"=>"float"}
     ]
   end
 end

spec/swagger_v2/param_type_spec.rb

@@ -26,7 +26,6 @@ def app
     expect(subject).to eq [{
       "in"=>"formData",
       "name"=>"input",
-      "description"=>nil,
       "type"=>"string",
       "required"=>true
     }]

spec/swagger_v2/param_values_spec.rb

@@ -47,7 +47,6 @@ def first_parameter_info(request)
       expect(plain_array).to eq [{
         "in"=>"formData",
         "name"=>"letter",
-        "description"=>nil,
         "type"=>"string",
         "required"=>true,
         "enum"=>["a", "b", "c"]
@@ -62,7 +61,6 @@ def first_parameter_info(request)
       expect(array_in_proc).to eq [{
         "in"=>"formData",
         "name"=>"letter",
-        "description"=>nil,
         "type"=>"string",
         "required"=>true,
         "enum"=>["d", "e", "f"]
@@ -77,7 +75,6 @@ def first_parameter_info(request)
       expect(range_letter).to eq [{
         "in"=>"formData",
         "name"=>"letter",
-        "description"=>nil,
         "type"=>"string",
         "required"=>true
       }]
@@ -89,7 +86,6 @@ def first_parameter_info(request)
       expect(range_integer).to eq [{
         "in"=>"formData",
         "name"=>"integer",
-        "description"=>nil,
         "type"=>"integer",
         "required"=>true,
         "format"=>"int32",
@@ -135,7 +131,6 @@ def first_parameter_info(request)
       expect(non_array_in_proc).to eq [{
         "in"=>"formData",
         "name"=>"letter",
-        "description"=>nil,
         "type"=>"string",
         "required"=>true,
         "enum"=>"string"
@@ -150,7 +145,6 @@ def first_parameter_info(request)
       expect(range_float).to eq [{
         "in"=>"formData",
         "name"=>"float",
-        "description"=>nil,
         "type"=>"number",
         "required"=>true,
         "format"=>"float"