swagger_yard 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 9aeaddf2ad2b175e4bfdc57babde3aa86ee99062
-  data.tar.gz: ff4b60b5e565142fb1fbca9a965df9ac966c1de1
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MjdkMTcwZWU5NTNhNjNhNjA0NzhlN2ZjMWZmMzZlMDUxZTI1NWNiOA==
+  data.tar.gz: !binary |-
+    MjAxYzIwNDYyNzc1MjEyMGU0MzIyNjAyZmU5OTI4YjA4MzFmMzRhOA==
 SHA512:
-  metadata.gz: 803a430a06eb91d2b853a9e1eccd45920d7047db36181076e53aec1e64ebc43a2e288cbab11f4541bb43e8d37f11b7f9822d0557065cd0f1ac92389ada974643
-  data.tar.gz: 19ce8dba724574bc55588c3ee5b913b3416ee18e24b26818e8ed5862637df439d8b83ddb3e54fbd1477594cc29d13d43cbe9d6352b327becf9e4d52aa19b6b49
+  metadata.gz: !binary |-
+    MDhhNWJkNDJhNWI3ODQyZTI0OGQ3ZmM4ZGE4MzYzMzgwNWU3YmM2N2MyMTAz
+    NGM3MDVkOTM1MDMwMDYxYTU1MjE4YTUyZWNlZmM0OWY3NjFhYjI0Mzc4ZDFk
+    ODUxODdkZWQ4YWNiY2Q1YTQ0YjMwODRjMzI3ZDQ0NWQwYWQ1Nzc=
+  data.tar.gz: !binary |-
+    NWFkMDRjMGE1MGYzYzE1ZWQ2NGRiMjRiMmZkOWQ5YjliZGYzYWJlZDFjOWE5
+    YzE2YWM0N2E2MzA4MDI4NzhmNTk0YjA3OTI2ODdjODUyZDU5OGNjNmE5NDBj
+    OWUyNGEyYTc3OGYyNDhmMTgxOTYzM2YwMzFhOWJmN2JkMTcwNDI=

data/README.md

@@ -38,6 +38,8 @@ are indicated inside square-brackets (e.g., `[string]`) as part of a YARD tag.
   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>]`.
+- An object definition can include the property definitions of its fields, and / or of an additional property for any remaining allowed fields. E.g., `[object<name: string, age: integer,  string >]`
+- 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" }`.
@@ -156,8 +158,9 @@ end
 ```
 
 ## Authorization ##
+### API Key auth ###
 
-Currently, SwaggerYard only supports API Key auth descriptions. Start by adding `@authorization` to your `ApplicationController`.
+SwaggerYard supports API Key auth descriptions. Start by adding `@authorization` to your `ApplicationController`.
 
 ```ruby
 #
@@ -177,6 +180,28 @@ class PetController < ApplicationController
 end
 ```
 
+### Custom security definitions (OAuth2) ###
+
+Additionally SwaggerYard also supports custom [security definitions](http://swagger.io/specification/#securityDefinitionsObject). You can define these in your configuration like:
+
+```ruby
+SwaggerYard.configure do |config|
+  config.security_definitions['petstore_oauth'] = {
+    type: "oauth2",
+    authorizationUrl: "http://swagger.io/api/oauth/dialog",
+    flow: :implicit
+  }
+end
+```
+
+Then you can also use these authorizations from your controller or actions in a controller.
+
+```ruby
+# @authorize_with petstore_oauth
+class PetController < ApplicationController
+end
+```
+
 ## UI ##
 
 We suggest using something like [swagger-ui_rails](https://github.com/3scale/swagger-ui_rails/tree/dev-2.1.3) for your UI needs inside of Rails.

data/lib/swagger_yard/configuration.rb

@@ -6,6 +6,7 @@ module SwaggerYard
     attr_accessor :enable, :reload
     attr_accessor :controller_path, :model_path
     attr_accessor :path_discovery_function
+    attr_accessor :security_definitions
 
     def initialize
       self.swagger_version = "2.0"
@@ -14,6 +15,7 @@ module SwaggerYard
       self.reload = true
       self.title = "Configure title with SwaggerYard.config.title"
       self.description = "Configure description with SwaggerYard.config.description"
+      self.security_definitions = {}
     end
 
     def swagger_spec_base_path=(ignored)

data/lib/swagger_yard/resource_listing.rb

@@ -43,7 +43,10 @@ module SwaggerYard
     end
 
     def security_objects
-      Hash[authorizations.map {|auth| [auth.name, auth.to_h]}]
+      controllers # triggers controller parsing in case it did not happen before
+      SwaggerYard.config.security_definitions.merge(
+        Hash[authorizations.map {|auth| [auth.name, auth.to_h]}]
+      )
     end
 
     private

data/lib/swagger_yard/type.rb

@@ -1,89 +1,34 @@
 module SwaggerYard
   class Type
     def self.from_type_list(types)
-      parts = types.first.split(/[<>]/)
-      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
-        when /^object$/i
-          options[:object] = parts[1..-1]
-        else
-          name = parts.first
-          options[:format] = parts.last
-        end
-      end
-      new(name, options)
+      new(types.first)
     end
 
-    attr_reader :name, :array, :enum, :object
+    attr_reader :name, :source, :schema
 
-    def initialize(name, options = {})
-      @name    = Model.mangle(name) if name
-      @array   = options[:array]
-      @enum    = options[:enum]
-      @format  = options[:format]
-      @pattern = options[:pattern]
-      @object  = options[:object]
+    def initialize(string)
+      @source  = string
+      @schema  = TypeParser.new.json_schema(string)
+      @name    = name_for(@schema)
+      @name    = name_for(@schema['items']) if @name == 'array'
     end
 
     # TODO: have this look at resource listing?
     def ref?
-      /[[:upper:]]/.match(name)
+      schema["$ref"]
     end
 
     def model_name
       ref? ? name : nil
     end
 
-    alias :array? :array
-    alias :enum? :enum
-    alias :object? :object
-
-    def json_type
-      type, format = name, @format
-      case name
-      when "float", "double"
-        type = "number"
-        format = name
-      when "date-time", "date", "time", "uuid"
-        type = "string"
-        format = name
-      end
-
-      hsh = { "type" => type }
-      hsh["format"] = format if format
-      hsh["pattern"] = @pattern if @pattern
-      hsh
-    end
-
     def to_h
-      type = if ref?
-        { "$ref" => "#/definitions/#{name}"}
-      elsif enum?
-        { "type" => "string", "enum" => @enum }
-      else
-        json_type
-      end
+      schema
+    end
 
-      if array?
-        { "type" => "array", "items" => type }
-      elsif object?
-        {
-          "type" => "object",
-          "additionalProperties" => Type.from_type_list([object.join("<")]).to_h
-        }
-      else
-        type
-      end
+    private
+    def name_for(schema)
+      schema["type"] || schema["$ref"][%r'#/definitions/(.*)', 1]
     end
   end
 end

data/lib/swagger_yard/type_parser.rb

@@ -0,0 +1,129 @@
+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(: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) |
+                          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' => "#/definitions/#{name}" }
+          else
+            { 'type' => name }
+          end
+        end
+      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
+      @parser = Parser.new
+      @xform  = Transform.new
+    end
+
+    def parse(str)
+      @parser.parse(str)
+    end
+
+    def json_schema(str)
+      @xform.apply(parse(str))
+    rescue Parslet::ParseFailed => e
+      raise ArgumentError, "invalid type: #{e.message}"
+    end
+  end
+end

data/lib/swagger_yard/version.rb

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

data/lib/swagger_yard.rb

@@ -2,6 +2,7 @@ require "yard"
 require "json"
 require "swagger_yard/configuration"
 require "swagger_yard/type"
+require "swagger_yard/type_parser"
 require "swagger_yard/parameter"
 require "swagger_yard/property"
 require "swagger_yard/operation"

metadata

@@ -1,125 +1,167 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.7
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-26 00:00:00.000000000 Z
+date: 2016-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: parslet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-its
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: apivore
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - <=
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - <=
+      - !ruby/object:Gem::Version
+        version: 2.4.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: bourne
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: wwtd
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: SwaggerYard API doc gem that uses YARD to parse the docs for a REST rails
@@ -145,6 +187,7 @@ files:
 - lib/swagger_yard/resource_listing.rb
 - lib/swagger_yard/swagger.rb
 - lib/swagger_yard/type.rb
+- lib/swagger_yard/type_parser.rb
 - lib/swagger_yard/version.rb
 homepage: http://www.synctv.com
 licenses:
@@ -156,19 +199,18 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: SwaggerYard API doc through YARD
 test_files: []
-has_rdoc: