swagger_yard 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 756c19df66b9851bc539daa6a77ba78b00814a73e514411c03ed036aaa0c2921
-  data.tar.gz: fa7b4ca209d1654df04d659f57c4e38803ce90c4c0a65d45c1aef7f19f655978
+  metadata.gz: 17346f3dae0e585379c27fc085e3dba2d22546eb5b01f31e2575ea1c2237e95c
+  data.tar.gz: a346029b12de6f15c72d0caa3b4bd5e59ccff4741c474e7bb3ecfa70a8dc878e
 SHA512:
-  metadata.gz: e00185e0b6e4d36c9933f3567b6223a7918ec47fe3a31f54a08d87442306efa3b6398a83cb820e4e04839f0b475102463963df580a75fd3918f974c014269993
-  data.tar.gz: ef4cdc1187050861e1bc4bfe6a23c223473e86def53ada9d65320c853a79e71c1d7ddcfb62eb9f9d69b5fab34a68f04503bda6f7825881a12021d9fb985d5e0f
+  metadata.gz: 91f408ddf67843e217bdac7a69e18e67b513389e7ccb42b8f1a1a27d7781deefc65628fc7239909a3b4a8d9dc7c66236bc3e0bb076e623b93371bb9929517a4c
+  data.tar.gz: a7a235cad5fbf1f2289c216562bdf7814721589393facf775fac2a39e84e589384d346db16af05c58760ec8e08889b3173e36aae41052e839e80636e76d23f27

data/README.md

@@ -110,7 +110,7 @@ end
 
 ### Model ###
 
-Each model to be exposed in the specification must have a `@model` tag. Model properties are specified with `@property` tags.
+Each model to be exposed in the specification must have a `@model` tag. Model properties are specified with `@property` tags. JSON Schema `additionalProperties` can be specified with `@additional_properties <type>` where `<type>` is any type defined elsewhere, or simply `false` to denote a closed model (`additionalProperties: false`).
 
 ```ruby
 #
@@ -120,6 +120,7 @@ Each model to be exposed in the specification must have a `@model` tag. Model pr
 # @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
+# @additional_properties string
 #
 class Pet
 end
@@ -179,6 +180,8 @@ Types of things (parameters or responses of an operation, properties of a model)
 - Structured data like objects, arrays, pairs, etc., definitions can also be nested; E.g., `[object<pairs:array<object<right:integer,left:integer>>>]`
 - 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}$" }`.
+- A union of two or more sub-types is expressed as `(A | B)` (parentheses required). This translates to `oneOf:` in JSON Schema.
+- An intersection of two or more sub-types is expressed as `(A & B)` (parentheses required). This translates to `allOf:` in JSON Schema.
 
 ### Options ###
 

data/lib/swagger_yard.rb

@@ -112,6 +112,7 @@ module SwaggerYard
       ::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("Additional properties", :additional_properties)
       ::YARD::Tags::Library.define_tag("Authorization", :authorization, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Authorization Use", :authorize_with)
       # @example is a core YARD tag, let's use it

data/lib/swagger_yard/model.rb

@@ -5,7 +5,8 @@ module SwaggerYard
   #
   class Model
     include Example
-    attr_reader :id, :discriminator, :inherits, :description, :properties
+    attr_reader :id, :discriminator, :inherits,
+      :description, :properties, :additional_properties
 
     def self.from_yard_object(yard_object)
       new.tap do |model|
@@ -41,7 +42,7 @@ module SwaggerYard
       properties.detect {|prop| prop.name == key }
     end
 
-    TAG_ORDER = %w(model inherits discriminator property example)
+    TAG_ORDER = %w(model inherits discriminator property example additional_properties)
 
     def parse_tags(tags)
       sorted_tags = tags.each_with_index.sort_by { |t,i|
@@ -72,6 +73,8 @@ module SwaggerYard
           else
             self.example = tag.text
           end
+        when "additional_properties"
+          @additional_properties = Type.new(tag.text).schema
         end
       end
 

data/lib/swagger_yard/swagger.rb

@@ -158,6 +158,7 @@ module SwaggerYard
 
       h["example"] = mod.example if mod.example
 
+      h["additionalProperties"] = mod.additional_properties if !mod.additional_properties.nil?
       h
     end
 

data/lib/swagger_yard/type_parser.rb

@@ -26,6 +26,8 @@ module SwaggerYard
 
       rule(:external_identifier) { name.as(:namespace) >> str('#') >> identifier.as(:identifier) }
 
+      rule(:_false)      { str('false').as(:false) }
+
       rule(:regexp)     { stri('regex') >> match['Pp'].maybe >> space >>
                           str('<') >> (str('\\\\') | str('\\>') | match['[^>]']).repeat.as(:regexp) >> str('>') }
 
@@ -43,10 +45,17 @@ module SwaggerYard
 
       rule(:formatted)  { name.as(:name) >> spaced('<') >> name.as(:format) >> spaced('>') }
 
+      rule(:union)      { spaced('(') >> type >> (spaced('|') >> type).repeat >> spaced(')') }
+
+      rule(:intersect)  { spaced('(') >> type >> (spaced('&') >> type).repeat >> spaced(')') }
+
       rule(:type)       { enum.as(:enum) |
                           array.as(:array) |
                           object.as(:object) |
                           formatted.as(:formatted) |
+                          union.as(:union) |
+                          intersect.as(:intersect) |
+                          _false |
                           external_identifier.as(:external_identifier) |
                           identifier.as(:identifier) |
                           regexp }
@@ -77,16 +86,9 @@ module SwaggerYard
       end
 
       rule(external_identifier: { namespace: simple(:namespace), identifier: simple(:identifier) }) do
-        prefix, name = namespace.to_s, identifier.to_s
-        unless url = SwaggerYard.config.external_schema[prefix]
-          raise UndefinedSchemaError, "unknown prefix #{prefix} for #{name}"
-        end
-        uri = URI(url)
-        fragment = uri.fragment ? "##{uri.fragment}" : model_path
-        uri.fragment = nil
-        fragment += '/' unless fragment.end_with?('/')
-        url = uri.to_s
-        { '$ref' => "#{url}#{fragment}#{Model.mangle(name)}"}
+        prefix, name  = namespace.to_s, identifier.to_s
+        url, fragment = resolve_uri.call(name, prefix)
+        { '$ref' => "#{url}#{fragment}#{Model.mangle(name)}" }
       end
 
       rule(formatted: { name: simple(:name), format: simple(:format) }) do
@@ -99,6 +101,8 @@ module SwaggerYard
 
       rule(value: simple(:value)) { value.to_s }
 
+      rule(false: simple(:false)) { false }
+
       rule(enum: subtree(:values)) do
         { 'type' => 'string', 'enum' => Array(values) }
       end
@@ -125,6 +129,14 @@ module SwaggerYard
           result.update additional.first unless additional.empty?
         end
       end
+
+      rule(union: subtree(:types)) do
+        { 'oneOf' => Array(types) }
+      end
+
+      rule(intersect: subtree(:types)) do
+        { 'allOf' => Array(types) }
+      end
     end
 
     def initialize(model_path = Type::MODEL_PATH)
@@ -138,9 +150,21 @@ module SwaggerYard
     end
 
     def json_schema(str)
-      @xform.apply(parse(str), model_path: @model_path)
+      @xform.apply(parse(str),
+                   model_path: @model_path,
+                   resolve_uri: ->(name, prefix) { resolve_uri(name, prefix) })
     rescue Parslet::ParseFailed => e
       raise InvalidTypeError, "'#{str}': #{e.message}"
     end
+
+    def resolve_uri(name, prefix)
+      unless url = SwaggerYard.config.external_schema[prefix]
+        raise UndefinedSchemaError, "unknown prefix #{prefix} for #{name}"
+      end
+      uri, fragment = url.split '#'
+      fragment = fragment ? "##{fragment}" : @model_path
+      fragment += '/' unless fragment.end_with?('/')
+      [uri, fragment]
+    end
   end
 end

data/lib/swagger_yard/type_parser.rb.~15b1c21e39906b88fcc3b6ec11649ad1a159adbf~

@@ -0,0 +1,146 @@
+require 'parslet'
+
+module SwaggerYard
+  class TypeParser
+    class Parser < Parslet::Parser
+      # Allow for whitespace surrounding a string value
+      def spaced(arg)
+        space >> str(arg) >> space
+      end
+
+      def stri(str)
+        key_chars = str.split(//)
+        key_chars.collect! { |char| match["#{char.upcase}#{char.downcase}"] }.
+          reduce(:>>)
+      end
+
+      rule(:space)      { match[" \n"].repeat }
+
+      rule(:id_char)    { match['-a-zA-Z0-9_'].repeat }
+
+      rule(:id_start)   { match('[a-zA-Z_]') }
+
+      rule(:name)       { id_start >> id_char }
+
+      rule(:identifier) { name >> (str('::') >> name).repeat }
+
+      rule(:external_identifier) { name.as(:namespace) >> str('#') >> identifier.as(:identifier) }
+
+      rule(:regexp)     { stri('regex') >> match['Pp'].maybe >> space >>
+                          str('<') >> (str('\\\\') | str('\\>') | match['[^>]']).repeat.as(:regexp) >> str('>') }
+
+      rule(:enum_list)  { name.as(:value) >> (spaced(',') >> name.as(:value)).repeat }
+
+      rule(:enum)       { stri('enum') >> spaced('<') >> enum_list >> spaced('>') }
+
+      rule(:array)      { stri('array') >> spaced('<') >> type >> spaced('>') }
+
+      rule(:pair)       { (name.as(:property) >> spaced(':') >> type.as(:type)).as(:pair) }
+
+      rule(:pairs)      { pair >> (spaced(',') >> pair).repeat >> (spaced(',') >> type.as(:additional)).maybe }
+
+      rule(:object)     { stri('object') >> spaced('<') >> (pairs | type.as(:additional)) >> spaced('>') }
+
+      rule(:formatted)  { name.as(:name) >> spaced('<') >> name.as(:format) >> spaced('>') }
+
+      rule(:type)       { enum.as(:enum) |
+                          array.as(:array) |
+                          object.as(:object) |
+                          formatted.as(:formatted) |
+                          external_identifier.as(:external_identifier) |
+                          identifier.as(:identifier) |
+                          regexp }
+
+      root :type
+    end
+
+    class Transform < Parslet::Transform
+      rule(identifier: simple(:id)) do
+        v = id.to_s
+        case v
+        when /^array$/i
+          { 'type' => 'array', 'items' => { 'type' => 'string' } }
+        when /^object$/i
+          { 'type' => 'object' }
+        when "float", "double"
+          { 'type' => 'number', 'format' => v }
+        when "date-time", "date", "time", "uuid"
+          { 'type' => 'string', 'format' => v }
+        else
+          name = Model.mangle(v)
+          if /[[:upper:]]/.match(name)
+            { '$ref' => "#{model_path}#{name}" }
+          else
+            { 'type' => name }
+          end
+        end
+      end
+
+      rule(external_identifier: { namespace: simple(:namespace), identifier: simple(:identifier) }) do
+        prefix, name = namespace.to_s, identifier.to_s
+        unless url = SwaggerYard.config.external_schema[prefix]
+          raise UndefinedSchemaError, "unknown prefix #{prefix} for #{name}"
+        end
+        uri = URI(url)
+        fragment = uri.fragment ? "##{uri.fragment}" : model_path
+        uri.fragment = nil
+        fragment += '/' unless fragment.end_with?('/')
+        url = uri.to_s
+        { '$ref' => "#{url}#{fragment}#{Model.mangle(name)}"}
+      end
+
+      rule(formatted: { name: simple(:name), format: simple(:format) }) do
+        { 'type' => name.to_s, 'format' => format.to_s }
+      end
+
+      rule(regexp: simple(:pattern)) do
+        { 'type' => 'string', 'pattern' => pattern.to_s.gsub('\\\\', '\\').gsub('\>', '>') }
+      end
+
+      rule(value: simple(:value)) { value.to_s }
+
+      rule(enum: subtree(:values)) do
+        { 'type' => 'string', 'enum' => Array(values) }
+      end
+
+      rule(array: subtree(:type)) do
+        { 'type' => 'array', 'items' => type }
+      end
+
+      rule(pair: { property: simple(:prop), type: subtree(:type) }) do
+        { 'properties' => { prop.to_s => type } }
+      end
+
+      rule(additional: subtree(:type)) do
+        { 'additionalProperties' => type }
+      end
+
+      rule(object: subtree(:properties)) do
+        { 'type' => 'object' }.tap do |result|
+          all_props = Array === properties ? properties : [properties]
+          props, additional = all_props.partition {|pr| pr['properties'] }
+          props.each do |pr|
+            result['properties'] = (result['properties'] || {}).merge(pr['properties'])
+          end
+          result.update additional.first unless additional.empty?
+        end
+      end
+    end
+
+    def initialize(model_path = Type::MODEL_PATH)
+      @parser = Parser.new
+      @xform  = Transform.new
+      @model_path = model_path
+    end
+
+    def parse(str)
+      @parser.parse(str)
+    end
+
+    def json_schema(str)
+      @xform.apply(parse(str), model_path: @model_path)
+    rescue Parslet::ParseFailed => e
+      raise InvalidTypeError, "'#{str}': #{e.message}"
+    end
+  end
+end

data/lib/swagger_yard/type_parser.rb.~5b9ef33~

@@ -0,0 +1,151 @@
+require 'parslet'
+
+module SwaggerYard
+  class TypeParser
+    class Parser < Parslet::Parser
+      # Allow for whitespace surrounding a string value
+      def spaced(arg)
+        space >> str(arg) >> space
+      end
+
+      def stri(str)
+        key_chars = str.split(//)
+        key_chars.collect! { |char| match["#{char.upcase}#{char.downcase}"] }.
+          reduce(:>>)
+      end
+
+      rule(:space)      { match[" \n"].repeat }
+
+      rule(:id_char)    { match['-a-zA-Z0-9_'].repeat }
+
+      rule(:id_start)   { match('[a-zA-Z_]') }
+
+      rule(:name)       { id_start >> id_char }
+
+      rule(:identifier) { name >> (str('::') >> name).repeat }
+
+      rule(:external_identifier) { name.as(:namespace) >> str('#') >> identifier.as(:identifier) }
+
+      rule(:regexp)     { stri('regex') >> match['Pp'].maybe >> space >>
+                          str('<') >> (str('\\\\') | str('\\>') | match['[^>]']).repeat.as(:regexp) >> str('>') }
+
+      rule(:enum_list)  { name.as(:value) >> (spaced(',') >> name.as(:value)).repeat }
+
+      rule(:enum)       { stri('enum') >> spaced('<') >> enum_list >> spaced('>') }
+
+      rule(:array)      { stri('array') >> spaced('<') >> type >> spaced('>') }
+
+      rule(:pair)       { (name.as(:property) >> spaced(':') >> type.as(:type)).as(:pair) }
+
+      rule(:pairs)      { pair >> (spaced(',') >> pair).repeat >> (spaced(',') >> type.as(:additional)).maybe }
+
+      rule(:object)     { stri('object') >> spaced('<') >> (pairs | type.as(:additional)) >> spaced('>') }
+
+      rule(:formatted)  { name.as(:name) >> spaced('<') >> name.as(:format) >> spaced('>') }
+
+      rule(:type)       { enum.as(:enum) |
+                          array.as(:array) |
+                          object.as(:object) |
+                          formatted.as(:formatted) |
+                          external_identifier.as(:external_identifier) |
+                          identifier.as(:identifier) |
+                          regexp }
+
+      root :type
+    end
+
+    class Transform < Parslet::Transform
+      rule(identifier: simple(:id)) do
+        v = id.to_s
+        case v
+        when /^array$/i
+          { 'type' => 'array', 'items' => { 'type' => 'string' } }
+        when /^object$/i
+          { 'type' => 'object' }
+        when "float", "double"
+          { 'type' => 'number', 'format' => v }
+        when "date-time", "date", "time", "uuid"
+          { 'type' => 'string', 'format' => v }
+        else
+          name = Model.mangle(v)
+          if /[[:upper:]]/.match(name)
+            { '$ref' => "#{model_path}#{name}" }
+          else
+            { 'type' => name }
+          end
+        end
+      end
+
+      rule(external_identifier: { namespace: simple(:namespace), identifier: simple(:identifier) }) do
+        prefix, name  = namespace.to_s, identifier.to_s
+        url, fragment = resolve_uri.call(name, prefix)
+        { '$ref' => "#{url}#{fragment}#{Model.mangle(name)}" }
+      end
+
+      rule(formatted: { name: simple(:name), format: simple(:format) }) do
+        { 'type' => name.to_s, 'format' => format.to_s }
+      end
+
+      rule(regexp: simple(:pattern)) do
+        { 'type' => 'string', 'pattern' => pattern.to_s.gsub('\\\\', '\\').gsub('\>', '>') }
+      end
+
+      rule(value: simple(:value)) { value.to_s }
+
+      rule(enum: subtree(:values)) do
+        { 'type' => 'string', 'enum' => Array(values) }
+      end
+
+      rule(array: subtree(:type)) do
+        { 'type' => 'array', 'items' => type }
+      end
+
+      rule(pair: { property: simple(:prop), type: subtree(:type) }) do
+        { 'properties' => { prop.to_s => type } }
+      end
+
+      rule(additional: subtree(:type)) do
+        { 'additionalProperties' => type }
+      end
+
+      rule(object: subtree(:properties)) do
+        { 'type' => 'object' }.tap do |result|
+          all_props = Array === properties ? properties : [properties]
+          props, additional = all_props.partition {|pr| pr['properties'] }
+          props.each do |pr|
+            result['properties'] = (result['properties'] || {}).merge(pr['properties'])
+          end
+          result.update additional.first unless additional.empty?
+        end
+      end
+    end
+
+    def initialize(model_path = Type::MODEL_PATH)
+      @parser = Parser.new
+      @xform  = Transform.new
+      @model_path = model_path
+    end
+
+    def parse(str)
+      @parser.parse(str)
+    end
+
+    def json_schema(str)
+      @xform.apply(parse(str),
+                   model_path: @model_path,
+                   resolve_uri: ->(name, prefix) { resolve_uri(name, prefix) })
+    rescue Parslet::ParseFailed => e
+      raise InvalidTypeError, "'#{str}': #{e.message}"
+    end
+
+    def resolve_uri(name, prefix)
+      unless url = SwaggerYard.config.external_schema[prefix]
+        raise UndefinedSchemaError, "unknown prefix #{prefix} for #{name}"
+      end
+      uri, fragment = url.split '#'
+      fragment = fragment ? "##{fragment}" : @model_path
+      fragment += '/' unless fragment.end_with?('/')
+      [uri, fragment]
+    end
+  end
+end

data/lib/swagger_yard/version.rb

@@ -1,3 +1,3 @@
 module SwaggerYard
-  VERSION = "1.0.3"
+  VERSION = "1.0.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-22 00:00:00.000000000 Z
+date: 2020-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -208,6 +208,8 @@ files:
 - lib/swagger_yard/type.rb
 - lib/swagger_yard/type.rb.~master~
 - lib/swagger_yard/type_parser.rb
+- lib/swagger_yard/type_parser.rb.~15b1c21e39906b88fcc3b6ec11649ad1a159adbf~
+- lib/swagger_yard/type_parser.rb.~5b9ef33~
 - lib/swagger_yard/version.rb
 homepage: http://www.synctv.com
 licenses: