swagger_yard 0.3.7 → 0.4.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MjdkMTcwZWU5NTNhNjNhNjA0NzhlN2ZjMWZmMzZlMDUxZTI1NWNiOA==
-  data.tar.gz: !binary |-
-    MjAxYzIwNDYyNzc1MjEyMGU0MzIyNjAyZmU5OTI4YjA4MzFmMzRhOA==
+SHA1:
+  metadata.gz: ef1f9c99cbcdd6a637a1d68079ba1e2a0b1cb718
+  data.tar.gz: 17849b615de17e9ec974f9905202a8097daf0eba
 SHA512:
-  metadata.gz: !binary |-
-    MDhhNWJkNDJhNWI3ODQyZTI0OGQ3ZmM4ZGE4MzYzMzgwNWU3YmM2N2MyMTAz
-    NGM3MDVkOTM1MDMwMDYxYTU1MjE4YTUyZWNlZmM0OWY3NjFhYjI0Mzc4ZDFk
-    ODUxODdkZWQ4YWNiY2Q1YTQ0YjMwODRjMzI3ZDQ0NWQwYWQ1Nzc=
-  data.tar.gz: !binary |-
-    NWFkMDRjMGE1MGYzYzE1ZWQ2NGRiMjRiMmZkOWQ5YjliZGYzYWJlZDFjOWE5
-    YzE2YWM0N2E2MzA4MDI4NzhmNTk0YjA3OTI2ODdjODUyZDU5OGNjNmE5NDBj
-    OWUyNGEyYTc3OGYyNDhmMTgxOTYzM2YwMzFhOWJmN2JkMTcwNDI=
+  metadata.gz: e200703aa74c246766ec9dbeb448ab6fd7f8b036376f82bd8ae60d0c7b6abe4d1d1149ec662c45d4ab1d34af0f38ece20e909a501bcdae78ee9b038687aa1f68
+  data.tar.gz: 4877499f45c859a0d75ba2518d425a867f2dc072955c38ea49b5cbcaa13f8bd2322989a15f10cb39de1f8a6191057dfdb25333cdb6eef96bdf9aa339d54032e3

data/README.md

@@ -47,6 +47,31 @@ are indicated inside square-brackets (e.g., `[string]`) as part of a YARD tag.
   `[regex<PATTERN>]`. For example, `[regex<^.{3}$>]` produces JSON
   `{ "type": "string", "pattern": "^.{3}$" }`.
 
+### External Schema ###
+
+Types can be specified that refer to external JSON schema documents for their definition. External schema documents are expected to also define their models under a `definitions` top-level key like so:
+```
+{
+  "definitions": {
+    "MyStandardModel": {
+    }
+  }
+}
+```
+
+To register an external schema so that it can be referenced in places where you specify a type, configure SwaggerYard as follows:
+```ruby
+SwaggerYard.configure do |config|
+  config.external_schema mymodels: 'https://example.com/mymodels/v1.0'
+end
+```
+
+Then refer to models in the schema using the syntax `[mymodels#MyStandardModel]` where types are specified. This causes SwaggerYard to emit the following schema for the type:
+
+```
+{ "$ref": "https://example.com/mymodels/v1.0#/definitions/MyStandardModel" }
+```
+
 ### Options ###
 
 Parameter or property _options_ are expressed inside parenthesis immediately

data/lib/swagger_yard/api.rb

@@ -11,7 +11,7 @@ module SwaggerYard
           yard_object.add_tag YARD::Tags::Tag.new("path", path, [method]) if path
           path
         rescue => e
-          YARD::Logger.instance.warn e.message
+          SwaggerYard.log.warn e.message
           nil
         end
       end

data/lib/swagger_yard/api_declaration.rb

@@ -41,7 +41,7 @@ module SwaggerYard
       end
 
       if tag = yard_object.tags.detect {|t| t.tag_name == "resource_path"}
-        log.warn "DEPRECATED: @resource_path tag is obsolete."
+        SwaggerYard.log.warn "DEPRECATED: @resource_path tag is obsolete."
       end
 
       # we only have api_key auth, the value for now is always empty array

data/lib/swagger_yard/configuration.rb

@@ -9,13 +9,21 @@ module SwaggerYard
     attr_accessor :security_definitions
 
     def initialize
-      self.swagger_version = "2.0"
-      self.api_version = "0.1"
-      self.enable = false
-      self.reload = true
-      self.title = "Configure title with SwaggerYard.config.title"
-      self.description = "Configure description with SwaggerYard.config.description"
-      self.security_definitions = {}
+      @swagger_version = "2.0"
+      @api_version = "0.1"
+      @enable = false
+      @reload = true
+      @title = "Configure title with SwaggerYard.config.title"
+      @description = "Configure description with SwaggerYard.config.description"
+      @security_definitions = {}
+      @external_schema = {}
+    end
+
+    def external_schema(mappings = nil)
+      mappings.each do |prefix, url|
+        @external_schema[prefix.to_s] = url
+      end if mappings
+      @external_schema
     end
 
     def swagger_spec_base_path=(ignored)

data/lib/swagger_yard/operation.rb

@@ -90,6 +90,12 @@ module SwaggerYard
     # Example: [GET] /api/v2/ownerships
     # Example: [PUT] /api/v1/accounts/{account_id}
     def add_path_params_and_method(tag)
+      if @path && @http_method
+        SwaggerYard.log.warn 'multiple path tags not supported: ' \
+          "ignored [#{tag.types.first}] #{tag.text}"
+        return
+      end
+
       @path = tag.text
       @http_method = tag.types.first
 
@@ -113,6 +119,9 @@ module SwaggerYard
         existing.param_type     = parameter.param_type if parameter.from_path?
         existing.required     ||= parameter.required
         existing.allow_multiple = parameter.allow_multiple
+      elsif parameter.param_type == 'body' && @parameters.detect {|param| param.param_type == 'body'}
+        SwaggerYard.log.warn 'multiple body parameters invalid: ' \
+          "ignored #{parameter.name} for #{@api.api_declaration.class_name}##{ruby_method}"
       else
         @parameters << parameter
       end

data/lib/swagger_yard/parameter.rb

@@ -1,10 +1,11 @@
 module SwaggerYard
   class Parameter
-    attr_accessor :name, :description, :param_type, :required, :allow_multiple
+    attr_accessor :name, :type, :description, :param_type, :required, :allow_multiple
 
     def self.from_yard_tag(tag, operation)
-      description = tag.text
       name, options_string = tag.name.split(/[\(\)]/)
+      description = tag.text
+      description = name if description.strip.empty?
       type = Type.from_type_list(tag.types)
 
       options = {}

data/lib/swagger_yard/property.rb

@@ -26,11 +26,13 @@ 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"]
+        unless h['$ref']
+          h["description"] = description if description
+          if @nullable
+            h["x-nullable"] = true
+            if h["type"]
+              h["type"] = [h["type"], "null"]
+            end
           end
         end
       end

data/lib/swagger_yard/resource_listing.rb

@@ -30,12 +30,14 @@ module SwaggerYard
     end
 
     def path_objects
-      controllers.map(&:apis_hash).reduce({}, :merge)
+      controllers.map(&:apis_hash).reduce({}, :merge).tap do |paths|
+        warn_duplicate_operations(paths)
+      end
     end
 
     # Resources
     def tag_objects
-      controllers.map(&:to_tag)
+      controllers.sort {|a,b| a.resource.upcase <=> b.resource.upcase}.map(&:to_tag)
     end
 
     def model_objects
@@ -73,5 +75,18 @@ module SwaggerYard
         end
       end.flatten.select(&:valid?)
     end
+
+    def warn_duplicate_operations(paths)
+      operation_ids = []
+      paths.each do |path,ops|
+        ops.each do |method,op|
+          if operation_ids.include?(op['operationId'])
+            SwaggerYard.log.warn("duplicate operation #{op['operationId']}")
+            next
+          end
+          operation_ids << op['operationId']
+        end
+      end
+    end
   end
 end

data/lib/swagger_yard/type_parser.rb

@@ -24,6 +24,8 @@ module SwaggerYard
 
       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('>') }
 
@@ -45,6 +47,7 @@ module SwaggerYard
                           array.as(:array) |
                           object.as(:object) |
                           formatted.as(:formatted) |
+                          external_identifier.as(:external_identifier) |
                           identifier.as(:identifier) |
                           regexp }
 
@@ -73,6 +76,14 @@ module SwaggerYard
         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
+        { '$ref' => "#{url}#/definitions/#{Model.mangle(name)}"}
+      end
+
       rule(formatted: { name: simple(:name), format: simple(:format) }) do
         { 'type' => name.to_s, 'format' => format.to_s }
       end
@@ -123,7 +134,7 @@ module SwaggerYard
     def json_schema(str)
       @xform.apply(parse(str))
     rescue Parslet::ParseFailed => e
-      raise ArgumentError, "invalid type: #{e.message}"
+      raise InvalidTypeError, "'#{str}': #{e.message}"
     end
   end
 end

data/lib/swagger_yard/version.rb

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

data/lib/swagger_yard.rb

@@ -14,6 +14,10 @@ require "swagger_yard/api"
 require "swagger_yard/swagger"
 
 module SwaggerYard
+  class Error < StandardError; end
+  class InvalidTypeError < Error; end
+  class UndefinedSchemaError < Error; end
+
   class << self
     ##
     # Configuration for Swagger Yard, use like:
@@ -33,6 +37,10 @@ module SwaggerYard
       @configuration ||= Configuration.new
     end
 
+    def log
+      YARD::Logger.instance
+    end
+
     #
     # Use YARD to parse object tags from a file
     #

metadata

@@ -1,167 +1,181 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.4.0
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-29 00:00:00.000000000 Z
+date: 2018-04-05 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'
+        version: '12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '12'
 - !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'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !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
@@ -199,17 +213,17 @@ 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.8
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: SwaggerYard API doc through YARD