swagger_yard 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fe5802a169475d76a89dfdefa227b4e70f656851
-  data.tar.gz: 5a384463c1798693067ac7379093f28d1f194312
+  metadata.gz: b6d7e8bd82bb1384166a7b05b762bbfb31ae9940
+  data.tar.gz: b4094c3b0020e510234ff13632a7be76728bd625
 SHA512:
-  metadata.gz: 0bad20c5172a080f1939eb511eac7b2c6930eb7bd3cf5f408a83100432f453bf9645c47bbbddc5bf35b98ab522d5f6d7e31f7a7277c19efd0607afa1ddfce309
-  data.tar.gz: c6d2040c142826db3ecd4e02fe4a9be55d09369addb94db8ed4b0081f0f87119142b7cc6a7ca7a2ddfd3638a224a26f34af3ee9233a1b9d7ee4db5cb3810edde
+  metadata.gz: 01b6da87aaa978797af17e081421136c01441d22048666beb8aa6baadc15698110e443b0a263dac0f85c4b45f18e12f5d168bdd35a988aa54cd3799e0d8b9ac2
+  data.tar.gz: 9a8c5b69c3fbf57c17f44398f052ff994d1a640e3f7c0fcb2c54dc9ccfc4347ce1f80b5043f239244c1866ac421269294d367148ec81f0c9d5c0e54a4e66c940

data/README.md

@@ -34,9 +34,16 @@ Types of things (parameters or responses of an operation, properties of a model)
 are indicated inside square-brackets (e.g., `[string]`) as part of a YARD tag.
 
 - Model references should be Capitalized or CamelCased by convention.
-- Basic types (integer, boolean, string, etc) should be lowercased.
+- Basic types (integer, boolean, string, object, number, date, time, date-time,
+  uuid, etc.) should be lowercased.
 - An array of models or basic types is specified with `[array<...>]`.
 - An enum of allowed string values is specified with `[enum<one,two,three>]`.
+- JSON-Schema `format` attributes can be specified for basic types using
+  `<...>`. For example, `[integer<int64>]` produces JSON
+  `{ "type": "integer", "format": "int64" }`.
+- Regex pattern constraints can be specified for strings using
+  `[regex<PATTERN>]`. For example, `[regex<^.{3}$>]` produces JSON
+  `{ "type": "string", "pattern": "^.{3}$" }`.
 
 ### Options ###
 
@@ -46,11 +53,13 @@ following the parameter or property name.
 Examples:
 
 	# @parameter name(required) [string]  Name of the package
+	# @parameter age(nullable)  [integer] Age of package
 	# @parameter package(body)  [Package] Package object
 
 Possible parameters include:
 
 - `required`: indicates a required parameter or property.
+- `nullable`: indicates that JSON `null` is an allowed value for the property.
 - `multiple`: indicates a parameter may appear multiple times (usually in a
   query string, e.g., `param=a&param=b&param=c`)
 - `body`/`query`/`path`/`formData`: Indicates where the parameter is located.

data/lib/swagger_yard/api_declaration.rb

@@ -1,10 +1,13 @@
 module SwaggerYard
   class ApiDeclaration
-    attr_accessor :description, :resource, :resource_path
+    attr_accessor :description, :resource
     attr_reader :apis, :authorizations
 
-    def initialize(resource_listing)
-      @resource_listing = resource_listing
+    def self.from_yard_object(yard_object)
+      new.add_yard_object(yard_object)
+    end
+
+    def initialize
       @resource         = nil
       @apis             = {}
       @authorizations   = {}
@@ -14,30 +17,37 @@ module SwaggerYard
       !@resource.nil?
     end
 
-    def add_yard_objects(yard_objects)
-      yard_objects.each do |yard_object|
-        add_yard_object(yard_object)
-      end
-      self
-    end
-
     def add_yard_object(yard_object)
       case yard_object.type
       when :class # controller
-        add_listing_info(ListingInfo.new(yard_object))
-        add_authorizations_to_resource_listing(yard_object)
+        add_info(yard_object)
+        if valid?
+          yard_object.children.each do |child_object|
+            add_yard_object(child_object)
+          end
+        end
       when :method # actions
         add_api(yard_object)
       end
+      self
     end
 
-    def add_listing_info(listing_info)
-      @description   = listing_info.description
-      @resource      = listing_info.resource
-      @resource_path = listing_info.resource_path # required for valid? but nothing else
+    def add_info(yard_object)
+      @description = yard_object.docstring
+
+      if tag = yard_object.tags.detect {|t| t.tag_name == "resource"}
+        @resource = tag.text
+      end
+
+      if tag = yard_object.tags.detect {|t| t.tag_name == "resource_path"}
+        log.warn "DEPRECATED: @resource_path tag is obsolete."
+      end
 
       # we only have api_key auth, the value for now is always empty array
-      @authorizations = Hash[listing_info.authorizations.uniq.map {|k| [k, []]}]
+      @authorizations = Hash[yard_object.tags.
+                             select {|t| t.tag_name == "authorize_with"}.
+                             map(&:text).uniq.
+                             map {|k| [k, []]}]
     end
 
     def add_api(yard_object)
@@ -49,13 +59,6 @@ module SwaggerYard
       api.add_operation(yard_object)
     end
 
-    # HACK, requires knowledge of resource_listing
-    def add_authorizations_to_resource_listing(yard_object)
-      yard_object.tags.select {|t| t.tag_name == "authorization"}.each do |t|
-        @resource_listing.authorizations << Authorization.from_yard_object(t)
-      end
-    end
-
     def apis_hash
       Hash[apis.map {|path, api| [path, api.operations_hash]}]
     end

data/lib/swagger_yard/model.rb

@@ -6,17 +6,9 @@ module SwaggerYard
   class Model
     attr_reader :id
 
-    def self.from_yard_objects(yard_objects)
-      from_yard_object(yard_objects.detect {|o| o.type == :class })
-    end
-
     def self.from_yard_object(yard_object)
-      from_tags(yard_object.tags) if yard_object
-    end
-
-    def self.from_tags(tags)
       new.tap do |model|
-        model.parse_tags(tags)
+        model.parse_tags(yard_object.tags)
       end
     end
 

data/lib/swagger_yard/operation.rb

@@ -39,7 +39,7 @@ module SwaggerYard
     end
 
     def summary
-      @summary || description.split("\n\n").first
+      @summary || description.split("\n\n").first || ""
     end
 
     def to_h

data/lib/swagger_yard/property.rb

@@ -8,14 +8,15 @@ module SwaggerYard
     def self.from_tag(tag)
       name, options_string = tag.name.split(/[\(\)]/)
 
-      required = options_string.to_s.split(',').map(&:strip).include?('required')
+      options = options_string.to_s.split(',').map(&:strip)
 
-      new(name, tag.types, tag.text, required)
+      new(name, tag.types, tag.text, options)
     end
 
-    def initialize(name, types, description, required)
-      @name, @description, @required = name, description, required
-
+    def initialize(name, types, description, options)
+      @name, @description = name, description
+      @required = options.include?('required')
+      @nullable = options.include?('nullable')
       @type = Type.from_type_list(types)
     end
 
@@ -26,6 +27,12 @@ module SwaggerYard
     def to_h
       @type.to_h.tap do |h|
         h["description"] = description if description
+        if @nullable
+          h["x-nullable"] = true
+          if h["type"]
+            h["type"] = [h["type"], "null"]
+          end
+        end
       end
     end
   end

data/lib/swagger_yard/resource_listing.rb

@@ -51,22 +51,23 @@ module SwaggerYard
       return [] unless @model_path
 
       Dir[@model_path].map do |file_path|
-        Model.from_yard_objects(SwaggerYard.yard_objects_from_file(file_path))
-      end.compact.select(&:valid?)
+        SwaggerYard.yard_class_objects_from_file(file_path).map do |obj|
+          Model.from_yard_object(obj)
+        end
+      end.flatten.compact.select(&:valid?)
     end
 
     def parse_controllers
       return [] unless @controller_path
 
       Dir[@controller_path].map do |file_path|
-        create_api_declaration(file_path)
-      end.select(&:valid?)
-    end
-
-    def create_api_declaration(file_path)
-      yard_objects = SwaggerYard.yard_objects_from_file(file_path)
-
-      ApiDeclaration.new(self).add_yard_objects(yard_objects)
+        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
+      end.flatten.select(&:valid?)
     end
   end
 end

data/lib/swagger_yard/type.rb

@@ -2,20 +2,34 @@ module SwaggerYard
   class Type
     def self.from_type_list(types)
       parts = types.first.split(/[<>]/)
-      args = [parts.last]
-      case parts.first
-      when /^array$/i
-        args << true
-      when /^enum$/i
-        args = [nil, false, parts.last.split(/[,|]/)]
-      end if parts.size > 1
-      new(*args)
+      name = parts.last
+      options = {}
+      if parts.size > 1
+        case parts.first
+        when /^array$/i
+          options[:array] = true
+        when /^enum$/i
+          name = nil
+          options[:enum] = parts.last.split(/[,|]/)
+        when /^regexp?$/i
+          name = 'string'
+          options[:pattern] = parts.last
+        else
+          name = parts.first
+          options[:format] = parts.last
+        end
+      end
+      new(name, options)
     end
 
     attr_reader :name, :array, :enum
 
-    def initialize(name, array = false, enum = nil)
-      @name, @array, @enum = name, array, enum
+    def initialize(name, options = {})
+      @name    = name
+      @array   = options[:array]
+      @enum    = options[:enum]
+      @format  = options[:format]
+      @pattern = options[:pattern]
     end
 
     # TODO: have this look at resource listing?
@@ -31,18 +45,19 @@ module SwaggerYard
     alias :enum? :enum
 
     def json_type
-      type, format = name, nil
+      type, format = name, @format
       case name
       when "float", "double"
         type = "number"
         format = name
-      when "date-time", "date", "time"
+      when "date-time", "date", "time", "uuid"
         type = "string"
         format = name
       end
       {}.tap do |h|
         h["type"]   = type
         h["format"] = format if format
+        h["pattern"] = @pattern if @pattern
       end
     end
 

data/lib/swagger_yard/version.rb

@@ -1,3 +1,3 @@
 module SwaggerYard
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/swagger_yard.rb

@@ -10,7 +10,6 @@ require "swagger_yard/resource_listing"
 require "swagger_yard/api_declaration"
 require "swagger_yard/model"
 require "swagger_yard/api"
-require "swagger_yard/listing_info"
 require "swagger_yard/swagger"
 
 module SwaggerYard
@@ -35,24 +34,33 @@ module SwaggerYard
 
     #
     # Use YARD to parse object tags from a file
-    # 
+    #
     # @param file_path [string] The complete path to file
+    # @param types additional types by which to filter the result (:class/:module/:method)
     # @return [YARD] objects representing class/methods and tags from the file
-    # 
-    def yard_objects_from_file(file_path)
-      ::YARD::Registry.clear
+    #
+    def yard_objects_from_file(file_path, *types)
       ::YARD.parse(file_path)
-      ::YARD::Registry.all
+      ::YARD::Registry.all(*types).select {|co| co.file == file_path }
+    end
+
+    #
+    # Parse all objects in the file and return the class objects found.
+    #
+    # @param file_path [string] The complete path to file
+    # @return [YARD] objects representing classes from the file
+    #
+    def yard_class_objects_from_file(file_path)
+      yard_objects_from_file(file_path, :class)
     end
 
     ##
     # Register some custom yard tags used by swagger-ui
     def register_custom_yard_tags!
       ::YARD::Tags::Library.define_tag("Api resource", :resource)
-      ::YARD::Tags::Library.define_tag("Resource path", :resource_path)
+      ::YARD::Tags::Library.define_tag("Resource path", :resource_path) # TODO: remove deprecated tag
       ::YARD::Tags::Library.define_tag("Api path", :path, :with_types)
       ::YARD::Tags::Library.define_tag("Parameter", :parameter, :with_types_name_and_default)
-      ::YARD::Tags::Library.define_tag("Status code", :status_code)
       ::YARD::Tags::Library.define_tag("Response type", :response_type, :with_types)
       ::YARD::Tags::Library.define_tag("Error response message", :error_message, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Api Summary", :summary)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-03 00:00:00.000000000 Z
+date: 2015-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -138,7 +138,6 @@ files:
 - lib/swagger_yard/api_declaration.rb
 - lib/swagger_yard/authorization.rb
 - lib/swagger_yard/configuration.rb
-- lib/swagger_yard/listing_info.rb
 - lib/swagger_yard/model.rb
 - lib/swagger_yard/operation.rb
 - lib/swagger_yard/parameter.rb

data/lib/swagger_yard/listing_info.rb

@@ -1,19 +0,0 @@
-module SwaggerYard
-  class ListingInfo
-    attr_reader :description, :resource, :resource_path, :authorizations
-
-    def initialize(yard_object)
-      @description = yard_object.docstring
-
-      if tag = yard_object.tags.detect {|t| t.tag_name == "resource"}
-        @resource = tag.text
-      end
-
-      if tag = yard_object.tags.detect {|t| t.tag_name == "resource_path"}
-        @resource_path = tag.text.downcase
-      end
-
-      @authorizations = yard_object.tags.select {|t| t.tag_name == "authorize_with"}.map(&:text)
-    end
-  end
-end