Allow to set an example for an operation's parameter

lib/swagger_yard/openapi.rb

@@ -39,6 +39,7 @@ def parameters(params)
           "in"          => param.param_type
         }.tap do |h|
           schema = param.type.schema_with(model_path: model_path)
+          schema["example"] = param.example unless param.example.nil?
           h["schema"] = schema
           h["explode"] = true if !Array(param.allow_multiple).empty? && schema["items"]
         end

lib/swagger_yard/parameter.rb

@@ -1,14 +1,15 @@
 module SwaggerYard
   class Parameter
-    attr_accessor :name, :type, :description, :param_type, :required, :allow_multiple
+    attr_accessor :name, :type, :description, :param_type, :required, :allow_multiple, :example
 
     def self.from_yard_tag(tag)
       tag = SwaggerYard.requires_name_and_type(tag)
       return nil unless tag
 
       name, options_string = tag.name.split(/[\(\)]/)
-      description = tag.text
+      description, example = tag.text.to_s.split(/\s*--\s*/)
       description = name if description.nil? || description.strip.empty?
+      example = nil if !example.nil? && example.strip.empty?
       type = Type.from_type_list(tag.types)
 
       options = {}
@@ -21,21 +22,21 @@ def self.from_yard_tag(tag)
         end
       end
 
-      new(name, type, description, options)
+      new(name, type, description, example, options)
     end
 
     # TODO: support more variation in scope types
     def self.from_path_param(name)
-      new(name, Type.new("string"), "Scope response to #{name}", {
+      new(name, Type.new("string"), "Scope response to #{name}", nil, {
         required: true,
         allow_multiple: false,
         param_type: "path",
         from_path: true
       })
     end
 
-    def initialize(name, type, description, options={})
-      @name, @type, @description = name, type, description
+    def initialize(name, type, description, example, options={})
+      @name, @type, @description, @example = name, type, description, example
 
       @required = options[:required] || false
       @param_type = options[:param_type] || 'query'

spec/fixtures/dummy/app/controllers/pets_controller.rb

@@ -17,7 +17,7 @@ def index
 
   # return a Pet
   # @path [GET] /pets/{id}
-  # @parameter id [integer] The ID for the Pet
+  # @parameter id [integer] The ID for the Pet -- 1
   # @response_type [Pet]
   # @error_message [EmptyPet] 404 Pet not found
   # @error_message 400 Invalid ID supplied

spec/lib/swagger_yard/openapi_spec.rb

@@ -33,7 +33,7 @@
 
     its(["get", "responses"]) { are_expected.to include("default", 404, 400) }
 
-    its(["get", "parameters"]) { are_expected.to include(a_parameter_named("id")) }
+    its(["get", "parameters"]) { are_expected.to include(include("name" => "id", "schema" => include("example" => "1"))) }
 
     its(["get", "security"]) { is_expected.to eq([{'header_x_application_api_key' => []}])}
   end

spec/lib/swagger_yard/operation_spec.rb

@@ -69,6 +69,26 @@
     its("parameters.last.description") { is_expected.to eq("name") }
   end
 
+  context "with a declared parameter that has a description and an example" do
+    let(:tags) { [yard_tag("@path [GET] /hello"),
+                  yard_tag("@parameter name [string] Description -- Example Name")] }
+
+    its("parameters.count") { is_expected.to eq(1) }
+    its("parameters.last.name") { is_expected.to eq("name") }
+    its("parameters.last.description") { is_expected.to eq("Description") }
+    its("parameters.last.example") { is_expected.to eq("Example Name") }
+  end
+
+  context "with a declared parameter that has no description but has an example" do
+    let(:tags) { [yard_tag("@path [GET] /hello"),
+                  yard_tag("@parameter name [string] -- Example Name")] }
+
+    its("parameters.count") { is_expected.to eq(1) }
+    its("parameters.last.name") { is_expected.to eq("name") }
+    its("parameters.last.description") { is_expected.to eq("name") }
+    its("parameters.last.example") { is_expected.to eq("Example Name") }
+  end
+
   context "with a declared parameter that has no description (reversed name/type)" do
     let(:tags) { [yard_tag("@path [GET] /hello"),
                   yard_tag("@parameter [string] name")] }