swaggard 4.0.3 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cd440c54fb4a517bedb134570c0dd76ed67ef1ef1947d0bcd89dc72f70d89a8
-  data.tar.gz: cdc795955a2d5d3d89e570657da280fa6fb4873a5bd562f086def5871c035354
+  metadata.gz: 28d2106f9e0d61087b74c97d99c4e3e6c848b9bee4afa7fb6a828db0466cb134
+  data.tar.gz: 668252d84bbdc87a23ed4191cc5baae2c2c7dfbe2b06cb794d8a7fe947cbf70c
 SHA512:
-  metadata.gz: e0789daceebcc72d62aca37584b4a2163bc1d5de00d20e22d990a8556797492d29fda8ac85acdbacbfde76b8c985047db02b656e0c91686ac386be7b4c9f088f
-  data.tar.gz: d860cfcc26f4c3a6c241fb5409ed3077c8330023b171b6c8a729e300056166ee58afd94020f43598d271b488c12ec1192265cbcc8ac2d2ed8bbd62677b3be959
+  metadata.gz: fbc1a171bbb0b3eaf2d285e4eebb9e3b2d76196745865afb727de157be519be9604d12af0745c9d2a7d73a5b52f0916230e98372bbc94af67159552cf72302dc
+  data.tar.gz: a648d45fc2cffc78502e548ccafcfbc2ff4ece0bccee7a75b3d4827cffab98d1672304bca5d63bcd1b94f1f0dc4d7a8cd373faea5adf61ca356f4f553928493c

data/README.md

@@ -139,7 +139,7 @@ Add YARD comments to provide richer documentation:
 
 - `@tag name` — Group this controller under `name`. Defaults to the controller path if `ignore_untagged_controllers` is false.
 - `@query_parameter [type] name` — Query string parameter.
-- `@body_parameter [type] name` — Request body property. Generates a `requestBody` in the OpenAPI output.
+- `@body_parameter [type] name` — Request body property. Generates a `requestBody` in the OpenAPI output. Use `[type]!` to mark the property as required and `name(deprecated)` to mark it as deprecated.
 - `@form_parameter [type] name` — Form data parameter (`application/x-www-form-urlencoded`).
 - `@parameter_list` — Enum-style query parameter list.
 - `@response_class type` — Response schema type. Supports `Array<Type>` for array responses.
@@ -162,7 +162,7 @@ To document all controllers including those without a `@tag`:
 
 ### Models
 
-- `@attr [type] name` — Model attribute.
+- `@attr [type] name` — Model attribute. Use `!name` to mark the attribute as required and `name(deprecated)` to mark it as deprecated.
 - `@ignore_inherited` — Do not inherit properties from parent class.
 
 

data/lib/swaggard/parsers/property.rb

@@ -11,10 +11,11 @@ module Swaggard
         options, description = options_and_description.match(/\A(\[.*\])?(.*)\Z/).captures
         options = options ? options.gsub(/\[?\]?\s?/, '').split(',') : []
         description = description.strip
+        deprecated = name.gsub!(/\(deprecated\)\z/, '')
         required = name.gsub!(/^!/, '')
         type = Parsers::Type.run(yard_object.types.first)
 
-        Swaggard::Swagger::Property.new(name, type, description, required.present?, options)
+        Swaggard::Swagger::Property.new(name, type, description, required.present?, options, deprecated.present?)
       end
     end
   end

data/lib/swaggard/swagger/definition.rb

@@ -5,13 +5,14 @@ module Swaggard
       attr_reader :id
       attr_writer :description, :title, :ignore_inherited
 
-      def initialize(id, ancestors: [])
+      def initialize(id, ancestors: [], collection: false)
         @id = id
         @title = ''
         @properties = []
         @description = ''
         @ancestors = ancestors
         @ignore_inherited = false
+        @collection = collection
       end
 
       def add_property(property)
@@ -41,19 +42,31 @@ module Swaggard
       end
 
       def to_doc(definitions)
-        {}.tap do |doc|
-          doc['title'] = @title if @title.present?
-          doc['type']  = 'object'
+        all_properties = properties(definitions)
+        properties_hash = Hash[all_properties.map { |property| [property.id, property.to_doc] }]
+        required_properties = all_properties.select(&:required?).map(&:id)
 
-          doc['description'] = @description if @description.present?
+        if @collection
+          items = { 'type' => 'object', 'properties' => properties_hash }
+          items['required'] = required_properties if required_properties.any?
 
-          all_properties = properties(definitions)
+          {}.tap do |doc|
+            doc['title'] = @title if @title.present?
+            doc['type'] = 'array'
+            doc['description'] = @description if @description.present?
+            doc['items'] = items
+          end
+        else
+          {}.tap do |doc|
+            doc['title'] = @title if @title.present?
+            doc['type']  = 'object'
 
-          doc['properties'] =  Hash[all_properties.map { |property| [property.id, property.to_doc] }]
-          required_properties = all_properties.select(&:required?).map(&:id)
-          doc['required'] = required_properties if required_properties.any?
-        end
+            doc['description'] = @description if @description.present?
 
+            doc['properties'] = properties_hash
+            doc['required'] = required_properties if required_properties.any?
+          end
+        end
       end
 
     end

data/lib/swaggard/swagger/parameters/body.rb

@@ -72,15 +72,17 @@ module Swaggard
             elsif @options.present?
               result['enum'] = @options
             end
+            result['deprecated'] = true if @deprecated
             result
           end
 
           # Example: [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
           # Example: [Array]     status(required)  Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
           # Example: [Integer]   media[media_type_id]                          ID of the desired media type.
+          # Example: [Boolean]   uses_tobacco(deprecated)  Whether the patient uses tobacco.
           def parse(string)
             string.gsub!("\n", ' ')
-            data_type, required, name, options_and_description = string.match(/\A\[(\S*)\](!)?\s*([\w\[\]]*)\s*(.*)\Z/).captures
+            data_type, required, name, deprecated, options_and_description = string.match(/\A\[(\S*)\](!)?\s*([\w\[\]]*)(\(deprecated\))?\s*(.*)\Z/).captures
             options, description = options_and_description.match(/\A(\[.*\])?(.*)\Z/).captures
             options = options ? options.gsub(/\[?\]?\s?/, '').split(',') : []
 
@@ -89,6 +91,7 @@ module Swaggard
             @type = Parsers::Type.run(data_type)
             @required = required
             @options = options
+            @deprecated = deprecated.present?
           end
         end
       end

data/lib/swaggard/swagger/property.rb

@@ -5,22 +5,28 @@ module Swaggard
     class Property
       attr_reader :id, :type, :description
 
-      def initialize(name, type, description = '', required = false, options = [])
+      def initialize(name, type, description = '', required = false, options = [], deprecated = false)
         @id = name
         @type = type
         @description = description
         @required = required
         @options = options
+        @deprecated = deprecated
       end
 
       def required?
         @required
       end
 
+      def deprecated?
+        @deprecated
+      end
+
       def to_doc
         result = @type.to_doc
         result['description'] = @description if @description.present?
         result['enum'] = @options if @options.present?
+        result['deprecated'] = true if @deprecated
         result
       end
     end

data/lib/swaggard/version.rb

@@ -1,3 +1,3 @@
 module Swaggard
-  VERSION = '4.0.3'
+  VERSION = '4.1.0'
 end

data/spec/swaggard/parsers/property_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+
+describe Swaggard::Parsers::Property do
+  def yard_tag(name, text: 'A description', types: ['string'])
+    YARD::Tags::Tag.new('attr', text, types, name)
+  end
+
+  describe '.run' do
+    it 'parses a plain attribute' do
+      property = described_class.run(yard_tag('name'))
+
+      expect(property.id).to eq('name')
+      expect(property).not_to be_required
+      expect(property).not_to be_deprecated
+    end
+
+    it 'parses the required marker' do
+      property = described_class.run(yard_tag('!name'))
+
+      expect(property.id).to eq('name')
+      expect(property).to be_required
+    end
+
+    it 'parses the deprecated marker' do
+      property = described_class.run(yard_tag('uses_tobacco(deprecated)', types: ['boolean']))
+
+      expect(property.id).to eq('uses_tobacco')
+      expect(property).to be_deprecated
+      expect(property.to_doc).to include('deprecated' => true)
+    end
+
+    it 'combines the required and deprecated markers' do
+      property = described_class.run(yard_tag('!name(deprecated)'))
+
+      expect(property.id).to eq('name')
+      expect(property).to be_required
+      expect(property).to be_deprecated
+    end
+  end
+end

data/spec/swaggard/swagger/definition_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe Swaggard::Swagger::Definition do
+  let(:property) { Swaggard::Swagger::Property.new('name', Swaggard::Swagger::Type.new(:string)) }
+
+  describe '#to_doc' do
+    context 'when collection is false (default)' do
+      subject(:definition) { described_class.new('Foo') }
+
+      before { definition.add_property(property) }
+
+      it 'emits a type: object schema with inline properties' do
+        expect(definition.to_doc({})).to eq(
+          'type' => 'object',
+          'properties' => { 'name' => { 'type' => 'string' } }
+        )
+      end
+    end
+
+    context 'when collection is true' do
+      subject(:definition) { described_class.new('Foo_all', collection: true) }
+
+      before { definition.add_property(property) }
+
+      it 'emits a type: array schema with properties wrapped under items' do
+        expect(definition.to_doc({})).to eq(
+          'type' => 'array',
+          'items' => {
+            'type' => 'object',
+            'properties' => { 'name' => { 'type' => 'string' } }
+          }
+        )
+      end
+
+      context 'with required properties' do
+        let(:property) do
+          Swaggard::Swagger::Property.new('name', Swaggard::Swagger::Type.new(:string), '', true)
+        end
+
+        it 'places the required array inside items' do
+          doc = definition.to_doc({})
+
+          expect(doc['required']).to be_nil
+          expect(doc['items']['required']).to eq(['name'])
+        end
+      end
+    end
+  end
+end

data/spec/swaggard/swagger/parameters/body_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe Swaggard::Swagger::Parameters::Body do
+  subject(:body) { described_class.new('PetsController.create') }
+
+  def property_doc(name)
+    body.definition.to_doc({})['properties'][name]
+  end
+
+  describe '#add_property' do
+    it 'parses type, name and description' do
+      body.add_property('[String] name The name of the pet')
+
+      expect(property_doc('name')).to eq('type' => 'string', 'description' => 'The name of the pet')
+    end
+
+    it 'parses the required marker' do
+      body.add_property('[String]! name The name of the pet')
+
+      expect(body.definition.to_doc({})['required']).to eq(['name'])
+    end
+
+    it 'parses the deprecated marker' do
+      body.add_property('[Boolean] uses_tobacco(deprecated) Use lifestyle instead.')
+
+      expect(property_doc('uses_tobacco')).to eq(
+        'type' => 'boolean',
+        'description' => 'Use lifestyle instead.',
+        'deprecated' => true
+      )
+    end
+
+    it 'combines the required and deprecated markers' do
+      body.add_property('[String]! name(deprecated) The name of the pet')
+
+      expect(property_doc('name')['deprecated']).to be(true)
+      expect(body.definition.to_doc({})['required']).to eq(['name'])
+    end
+
+    it 'keeps enum options working alongside the deprecated marker' do
+      body.add_property('[String] status(deprecated) [active,inactive] The status')
+
+      expect(property_doc('status')).to eq(
+        'type' => 'string',
+        'description' => ' The status',
+        'enum' => %w[active inactive],
+        'deprecated' => true
+      )
+    end
+  end
+end

data/spec/swaggard/swagger/property_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe Swaggard::Swagger::Property do
+  describe '#to_doc' do
+    let(:type) { Swaggard::Swagger::Type.new(:string) }
+
+    it 'emits the type only by default' do
+      property = described_class.new('name', type)
+
+      expect(property.to_doc).to eq('type' => 'string')
+    end
+
+    it 'emits the description when present' do
+      property = described_class.new('name', type, 'The full name')
+
+      expect(property.to_doc).to eq('type' => 'string', 'description' => 'The full name')
+    end
+
+    it 'emits deprecated when the property is deprecated' do
+      property = described_class.new('name', type, '', false, [], true)
+
+      expect(property.to_doc).to eq('type' => 'string', 'deprecated' => true)
+      expect(property).to be_deprecated
+    end
+
+    it 'does not emit deprecated when the property is not deprecated' do
+      property = described_class.new('name', type)
+
+      expect(property.to_doc).not_to have_key('deprecated')
+      expect(property).not_to be_deprecated
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swaggard
 version: !ruby/object:Gem::Version
-  version: 4.0.3
+  version: 4.1.0
 platform: ruby
 authors:
 - Adrian Gomez
@@ -162,6 +162,10 @@ files:
 - spec/integration/openapi_spec.rb
 - spec/integration/swaggard_spec.rb
 - spec/spec_helper.rb
+- spec/swaggard/parsers/property_spec.rb
+- spec/swaggard/swagger/definition_spec.rb
+- spec/swaggard/swagger/parameters/body_spec.rb
+- spec/swaggard/swagger/property_spec.rb
 homepage: https://github.com/adrian-gomez/swaggard
 licenses:
 - MIT
@@ -199,3 +203,7 @@ test_files:
 - spec/integration/openapi_spec.rb
 - spec/integration/swaggard_spec.rb
 - spec/spec_helper.rb
+- spec/swaggard/parsers/property_spec.rb
+- spec/swaggard/swagger/definition_spec.rb
+- spec/swaggard/swagger/parameters/body_spec.rb
+- spec/swaggard/swagger/property_spec.rb