swagger_yard 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15d5836beac3af1865cfb811b531d4b3998cc5d4
-  data.tar.gz: b2017de06dd82f00ffeacb4dbf16fe2399e22b09
+  metadata.gz: 9aeaddf2ad2b175e4bfdc57babde3aa86ee99062
+  data.tar.gz: ff4b60b5e565142fb1fbca9a965df9ac966c1de1
 SHA512:
-  metadata.gz: 1ca5f85cf9b7543be72fee44ef44852d71947fd7ed20a34363666b540d3e441415ac2ce11b2aacee2a8e1460d298887152ff7972f87dd92065eebc302bbb3bdb
-  data.tar.gz: 2d87279b97f90bd3b69b7af502601c2013b62add6487d7d0ba2d7d661bab3341b64fc0ccf40e51afda8aedd54e9464a0d006e8f36fda07e52b440bb5cbdf447c
+  metadata.gz: 803a430a06eb91d2b853a9e1eccd45920d7047db36181076e53aec1e64ebc43a2e288cbab11f4541bb43e8d37f11b7f9822d0557065cd0f1ac92389ada974643
+  data.tar.gz: 19ce8dba724574bc55588c3ee5b913b3416ee18e24b26818e8ed5862637df439d8b83ddb3e54fbd1477594cc29d13d43cbe9d6352b327becf9e4d52aa19b6b49

data/README.md

@@ -96,7 +96,7 @@ class Accounts::OwnershipsController < ActionController::Base
 
   ##
   # Returns an ownership for an account by id
-  # 
+  #
   # @path [GET] /accounts/ownerships/{id}
   # @response_type [Ownership]
   # @error_message [EmptyOwnership] 404 Ownership not found
@@ -129,6 +129,32 @@ To then use your `Model` in your `Controller` documentation, add `@parameter`s:
 # @parameter pet(body) [Pet] The pet object
 ```
 
+To support Swagger Polymorphism, use `@discriminator` and `@inherits`:
+
+```ruby
+#
+# @model Pet
+#
+# @property id(required)    [integer]   the identifier for the pet
+# @property name  [Array<string>]    the names for the pet
+# @property age   [integer]   the age of the pet
+# @property relatives(required) [Array<Pet>] other Pets in its family
+# @discriminator petType(required) [string] the type of pet
+#
+class Pet
+end
+
+#
+# @model Dog
+#
+# @inherits Pet
+#
+# @property packSize(required) [integer] the size of the pack the dog is from
+#
+class Dog < Pet
+end
+```
+
 ## Authorization ##
 
 Currently, SwaggerYard only supports API Key auth descriptions. Start by adding `@authorization` to your `ApplicationController`.
@@ -178,7 +204,7 @@ ResourceListing
 |   -> Operation(s) (controller action with HTTP method)
 |     |
 |     -> Parameter(s) (action param)
-| 
+|
 -> Model (model)
   |
   -> Properties (model attributes)

data/lib/swagger_yard.rb

@@ -65,7 +65,9 @@ module SwaggerYard
       ::YARD::Tags::Library.define_tag("Error response message", :error_message, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Api Summary", :summary)
       ::YARD::Tags::Library.define_tag("Model resource", :model)
+      ::YARD::Tags::Library.define_tag("Model superclass", :inherits)
       ::YARD::Tags::Library.define_tag("Model property", :property, :with_types_name_and_default)
+      ::YARD::Tags::Library.define_tag("Model discriminator", :discriminator, :with_types_name_and_default)
       ::YARD::Tags::Library.define_tag("Authorization", :authorization, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Authorization Use", :authorize_with)
     end

data/lib/swagger_yard/model.rb

@@ -4,7 +4,7 @@ module SwaggerYard
   #   complex model object as defined by swagger schema
   #
   class Model
-    attr_reader :id
+    attr_reader :id, :discriminator, :inherits
 
     def self.from_yard_object(yard_object)
       new.tap do |model|
@@ -18,6 +18,7 @@ module SwaggerYard
 
     def initialize
       @properties = []
+      @inherits = []
     end
 
     def valid?
@@ -31,17 +32,42 @@ module SwaggerYard
           @id = Model.mangle(tag.text)
         when "property"
           @properties << Property.from_tag(tag)
+        when "discriminator"
+          prop = Property.from_tag(tag)
+          @properties << prop
+          @discriminator ||= prop.name
+        when "inherits"
+          @inherits << Model.mangle(tag.text)
         end
       end
 
       self
     end
 
-    def to_h
-      {}.tap do |h|
-        h["properties"] = Hash[@properties.map {|p| [p.name, p.to_h]}]
-        h["required"] = @properties.select(&:required?).map(&:name) if @properties.detect(&:required?)
+    def inherits_references
+      @inherits.map do |name|
+        {
+          "$ref" => "#/definitions/#{name}"
+        }
       end
     end
+
+    def to_h
+      h = {
+        "type" => "object",
+        "properties" => Hash[@properties.map {|p| [p.name, p.to_h]}]
+      }
+
+      h["required"] = @properties.select(&:required?).map(&:name) if @properties.detect(&:required?)
+      h["discriminator"] = @discriminator if @discriminator
+
+      # Polymorphism
+      h = { "allOf" => inherits_references + [h] } unless @inherits.empty?
+
+      # Description
+      h["description"] = @description if @description
+
+      h
+    end
   end
 end

data/lib/swagger_yard/resource_listing.rb

@@ -7,8 +7,8 @@ module SwaggerYard
     end
 
     def initialize(controller_path, model_path)
-      @model_path = model_path
-      @controller_path = controller_path
+      @model_paths = [*model_path].compact
+      @controller_paths = [*controller_path].compact
 
       @resource_to_file_path = {}
       @authorizations = []
@@ -47,25 +47,26 @@ module SwaggerYard
     end
 
     private
-    def parse_models
-      return [] unless @model_path
 
-      Dir[@model_path].map do |file_path|
-        SwaggerYard.yard_class_objects_from_file(file_path).map do |obj|
-          Model.from_yard_object(obj)
+    def parse_models
+      @model_paths.map do |model_path|
+        Dir[model_path.to_s].map do |file_path|
+          SwaggerYard.yard_class_objects_from_file(file_path).map do |obj|
+            Model.from_yard_object(obj)
+          end
         end
       end.flatten.compact.select(&:valid?)
     end
 
     def parse_controllers
-      return [] unless @controller_path
-
-      Dir[@controller_path].map do |file_path|
-        SwaggerYard.yard_class_objects_from_file(file_path).map do |obj|
-          obj.tags.select {|t| t.tag_name == "authorization"}.each do |t|
-            @authorizations << Authorization.from_yard_object(t)
+      @controller_paths.map do |controller_path|
+        Dir[controller_path.to_s].map do |file_path|
+          SwaggerYard.yard_class_objects_from_file(file_path).map do |obj|
+            obj.tags.select {|t| t.tag_name == "authorization"}.each do |t|
+              @authorizations << Authorization.from_yard_object(t)
+            end
+            ApiDeclaration.from_yard_object(obj)
           end
-          ApiDeclaration.from_yard_object(obj)
         end
       end.flatten.select(&:valid?)
     end

data/lib/swagger_yard/swagger.rb

@@ -1,19 +1,33 @@
 module SwaggerYard
   class Info
     def to_h
-      { "title"       => SwaggerYard.config.title,
+      {
+        "title"       => SwaggerYard.config.title,
         "description" => SwaggerYard.config.description,
-        "version"     => SwaggerYard.config.api_version }
+        "version"     => SwaggerYard.config.api_version
+      }
     end
   end
 
   class Swagger
     def to_h
-      { "swagger"  => "2.0",
-        "info"     => Info.new.to_h,
-        "host"     => URI(SwaggerYard.config.api_base_path).host,
-        "basePath" => URI(SwaggerYard.config.api_base_path).request_uri
-      }.merge(ResourceListing.all.to_h)
+      {
+        "swagger"  => "2.0",
+        "info"     => Info.new.to_h
+      }.merge(uri_info).merge(ResourceListing.all.to_h)
+    end
+
+    private
+
+    def uri_info
+      uri = URI(SwaggerYard.config.api_base_path)
+      host = uri.host
+      host = "#{uri.host}:#{uri.port}" unless uri.port == uri.default_port
+
+      {
+        'host' => host,
+        'basePath' => uri.request_uri
+      }
     end
   end
 end

data/lib/swagger_yard/type.rb

@@ -14,6 +14,8 @@ module SwaggerYard
         when /^regexp?$/i
           name = 'string'
           options[:pattern] = parts.last
+        when /^object$/i
+          options[:object] = parts[1..-1]
         else
           name = parts.first
           options[:format] = parts.last
@@ -22,7 +24,7 @@ module SwaggerYard
       new(name, options)
     end
 
-    attr_reader :name, :array, :enum
+    attr_reader :name, :array, :enum, :object
 
     def initialize(name, options = {})
       @name    = Model.mangle(name) if name
@@ -30,6 +32,7 @@ module SwaggerYard
       @enum    = options[:enum]
       @format  = options[:format]
       @pattern = options[:pattern]
+      @object  = options[:object]
     end
 
     # TODO: have this look at resource listing?
@@ -43,6 +46,7 @@ module SwaggerYard
 
     alias :array? :array
     alias :enum? :enum
+    alias :object? :object
 
     def json_type
       type, format = name, @format
@@ -54,11 +58,11 @@ module SwaggerYard
         type = "string"
         format = name
       end
-      {}.tap do |h|
-        h["type"]   = type
-        h["format"] = format if format
-        h["pattern"] = @pattern if @pattern
-      end
+
+      hsh = { "type" => type }
+      hsh["format"] = format if format
+      hsh["pattern"] = @pattern if @pattern
+      hsh
     end
 
     def to_h
@@ -69,8 +73,14 @@ module SwaggerYard
       else
         json_type
       end
+
       if array?
         { "type" => "array", "items" => type }
+      elsif object?
+        {
+          "type" => "object",
+          "additionalProperties" => Type.from_type_list([object.join("<")]).to_h
+        }
       else
         type
       end

data/lib/swagger_yard/version.rb

@@ -1,3 +1,3 @@
 module SwaggerYard
-  VERSION = "0.3.5"
+  VERSION = "0.3.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-29 00:00:00.000000000 Z
+date: 2016-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard