Allow to set @authorize_with for an explicit action in a controller

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
@@ -70,6 +71,16 @@ def response(resp, op)
       end
     end
 
+    def property(prop)
+      prop.type.schema_with(model_path: model_path).tap do |h|
+        unless h['$ref']
+          h["description"] = prop.description if prop.description && !prop.description.strip.empty?
+          h["nullable"] = true if prop.nullable
+          h["example"] = prop.example if prop.example
+        end
+      end
+    end
+
     def security_defs(security_objects)
       defs = super
       Hash[defs.map do |name, d|

lib/swagger_yard/operation.rb

@@ -6,6 +6,7 @@ class Response
 
   class Operation
     attr_accessor :description, :ruby_method
+    attr_accessor :authorizations
     attr_writer :summary
     attr_reader :path, :http_method
     attr_reader :parameters
@@ -36,6 +37,8 @@ def self.from_yard_object(yard_object, path_item)
             else
               operation.default_response.example = tag.text
             end
+          when "authorize_with"
+            operation.authorizations[tag.text] ||= []
           end
         end
 
@@ -50,6 +53,7 @@ def initialize(path_item)
       @parameters     = []
       @default_response = nil
       @responses = []
+      @authorizations = {}.merge(api_group.authorizations.to_h)
     end
 
     def summary

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'

lib/swagger_yard/swagger.rb

@@ -84,7 +84,7 @@ def operation(op)
       op_hash["description"] = op.description unless op.description.empty?
       op_hash["summary"]     = op.summary unless op.summary.empty?
 
-      authorizations = op.api_group.authorizations
+      authorizations = op.authorizations
       unless authorizations.empty?
         op_hash["security"] = authorizations.map {|k,v| { k => v} }
       end

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
@@ -225,6 +225,31 @@
 
   end
 
+  context "models" do
+    let(:model) { SwaggerYard::Model.from_yard_object(yard_class('MyModel', content)) }
+    let(:spec) { stub(path_objects: SwaggerYard::Paths.new([]), tag_objects: [],
+                      security_objects: [], model_objects: { model.id => model }) }
+
+    subject { described_class.new(spec).to_h["components"]["schemas"] }
+
+    context 'nullables' do
+      subject { super()['MyModel']['properties'] }
+
+      context "with a nullable flag" do
+        let(:content) { ['@model MyModel', '@property name(nullable) [string]  Name'] }
+
+        its(['name', 'type'])     { is_expected.to eq('string') }
+        its(['name', 'nullable']) { is_expected.to eq(true) }
+      end
+
+      context "with a nullable model" do
+        let(:content) { ['@model MyModel', '@property name(nullable) [Name]  Name'] }
+
+        its(['name']) { is_expected.to eq('$ref' => '#/components/schemas/Name') }
+      end
+    end
+  end
+
   context 'with config.openapi_version set and Swagger.new' do
     subject { SwaggerYard::Swagger.new.to_h }
     before { SwaggerYard.config.openapi_version = '3.0.0' }

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")] }