openapi3_parser 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c7e2585cb3bbdbda459519eb7e264dfd89f5745
-  data.tar.gz: 4fdbb4b547e626e1b0ba5f502b93107638af3655
+  metadata.gz: f60ae34f39675f7ce3616bd96dc3e383275d117d
+  data.tar.gz: 4ecf6bffd69c875778c4d096f29cf7b5deadbf7e
 SHA512:
-  metadata.gz: 498d2043a338970c66ef9d14590adb34ec2f7b65e751985f8d12a8c9506d63e09a9840e7521b00a953000af1e286917147fb4507be29f68a5c047aa9f124f7d8
-  data.tar.gz: 7fb4d6b168b514fa01056fa5be0026551ad02e0e47506e99516b14b290e450c0940031e82fc38bdc0f4c5d137d98d3a621f28d42bd6e5923f335a7c31255796e
+  metadata.gz: f5a96679f760117e345c9e992161444c06df7d667953fad6badf547dd83dee449b672cc9f265a26a7166e2cdec887d5205bf0dcda6abdbece2a2ce74aeb61153
+  data.tar.gz: 087aea7ab5f4abceb69b9acce6854f70dac44fca1620bde695d7dd1a7813ca1a468728e3cc5a08ab5ae31d5320c75459f9537ce584c6ffbff082ca796d9a3602

data/.gitignore

@@ -1 +1,4 @@
 /Gemfile.lock
+/pkg
+/.yardoc
+/doc

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 0.2.0
+
+- Allow defaulting to empty arrays and maps
+- Configure rubydoc
+- Types returned documented for the nodes
+

data/README.md

@@ -1,6 +1,6 @@
 # OpenAPI 3 Parser
 
-[![Build Status](https://travis-ci.org/kevindew/openapi_parser.svg?branch=master)](https://travis-ci.org/kevindew/openapi_parser)
+[![Build Status](https://travis-ci.org/kevindew/openapi3_parser.svg?branch=master)](https://travis-ci.org/kevindew/openapi3_parser)
 
 
 This is a parser/validator for [Open API 3][openapi-3] built in Ruby.
@@ -19,7 +19,11 @@ document.valid?
 document.paths["/"]
 ```
 
+Documentation for the API to navigate the OpenAPI nodes is available on
+[rubydoc.info][docs].
+
 [openapi-3]: https://github.com/OAI/OpenAPI-Specification
+[docs]: http://www.rubydoc.info/github/kevindew/openapi3_parser/Openapi3Parser/Nodes/Openapi
 
 ## Status
 

data/TODO.md

@@ -28,3 +28,4 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [ ] Improve the modelling of namespace
 - [ ] Set up nicer string representations of key classes to help them be
       debugged
+- [ ] Ensure Array and Map nodes return empty ones by default rather than nil

data/lib/openapi3_parser.rb

@@ -7,6 +7,12 @@ require "yaml"
 require "json"
 
 module Openapi3Parser
+  # For a variety of inputs this will construct an OpenAPI document. For a
+  # String/File input it will try to determine if the input is JSON or YAML.
+  #
+  # @param [String, Hash, File] input Source for the OpenAPI document
+  #
+  # @return [Document]
   def self.load(input)
     # working_directory ||= if input.respond_to?(:read)
     #                         File.dirname(input)
@@ -17,6 +23,13 @@ module Openapi3Parser
     Document.new(parse_input(input))
   end
 
+  # For a given string filename this will read the file and parse it as an
+  # OpenAPI document. It will try detect automatically whether the contents
+  # are JSON or YAML.
+  #
+  # @param [String] path Filename of the OpenAPI document
+  #
+  # @return [Document]
   def self.load_file(path)
     file = File.open(path)
     load(file)

data/lib/openapi3_parser/context.rb

@@ -18,12 +18,12 @@ module Openapi3Parser
     def stringify_namespace
       return "root" if namespace.empty?
       namespace
-        .map { |i| i.include?("/") ? %("#{i}") : i }
+        .map { |i| i.to_s.include?("/") ? %("#{i}") : i }
         .join("/")
     end
 
     def next_namespace(segment, next_input = nil)
-      next_input ||= input[segment]
+      next_input ||= input.nil? ? nil : input[segment]
       self.class.new(
         input: next_input,
         namespace: namespace + [segment],

data/lib/openapi3_parser/node_factories/array.rb

@@ -12,11 +12,13 @@ module Openapi3Parser
 
       def initialize(
         context,
+        default: [],
         value_input_type: nil,
         value_factory: nil,
         validate: nil
       )
         super(context)
+        @default = default
         @given_value_input_type = value_input_type
         @given_value_factory = value_factory
         @given_validate = validate
@@ -24,8 +26,8 @@ module Openapi3Parser
 
       private
 
-      attr_reader :given_value_input_type, :given_value_factory,
-                  :given_validate
+      attr_reader :default, :given_value_input_type,
+                  :given_value_factory, :given_validate
 
       def process_input(input)
         input.each_with_index.map do |value, i|

data/lib/openapi3_parser/node_factories/components.rb

@@ -78,6 +78,10 @@ module Openapi3Parser
           value_factory: NodeFactory::OptionalReference.new(factory)
         )
       end
+
+      def default
+        {}
+      end
     end
   end
 end

data/lib/openapi3_parser/node_factories/schema.rb

@@ -29,8 +29,8 @@ module Openapi3Parser
       field "uniqueItems", input_type: :boolean, default: false
       field "maxProperties", input_type: Integer
       field "minProperties", input_type: Integer, default: 0
-      field "required", input_type: ::Array
-      field "enum", input_type: ::Array
+      field "required", factory: :required_factory
+      field "enum", factory: :enum_factory
 
       field "type", input_type: String
       field "allOf", factory: :referenceable_schema_array
@@ -62,6 +62,18 @@ module Openapi3Parser
         Nodes::Schema.new(data, context)
       end
 
+      def required_factory(context)
+        NodeFactories::Array.new(
+          context,
+          default: nil,
+          value_input_type: String
+        )
+      end
+
+      def enum_factory(context)
+        NodeFactories::Array.new(context, default: nil)
+      end
+
       def disciminator_factory(context)
         NodeFactories::Discriminator.new(context)
       end
@@ -88,6 +100,7 @@ module Openapi3Parser
       def referenceable_schema_array(context)
         NodeFactories::Array.new(
           context,
+          default: nil,
           value_factory: NodeFactory::OptionalReference.new(self.class)
         )
       end

data/lib/openapi3_parser/node_factories/server_variable.rb

@@ -2,6 +2,7 @@
 
 require "openapi3_parser/nodes/server_variable"
 require "openapi3_parser/node_factory/object"
+require "openapi3_parser/node_factories/array"
 
 module Openapi3Parser
   module NodeFactories
@@ -9,15 +10,22 @@ module Openapi3Parser
       include NodeFactory::Object
 
       allow_extensions
-      field "enum", input_type: ::Array, validate: :validate_enum
+      field "enum", factory: :enum_factory, validate: :validate_enum
       field "default", input_type: String, required: true
       field "description", input_type: String
 
       private
 
+      def enum_factory(context)
+        NodeFactories::Array.new(
+          context,
+          default: nil,
+          value_input_type: String
+        )
+      end
+
       def validate_enum(input)
         return "Expected atleast one value" if input.empty?
-        "Expected String values" unless input.map(&:class).uniq == [String]
       end
 
       def build_object(data, context)

data/lib/openapi3_parser/node_factory.rb

@@ -45,6 +45,10 @@ module Openapi3Parser
       @node ||= build_valid_node
     end
 
+    def nil_input?
+      context.input.nil?
+    end
+
     private
 
     def validate(_input, _context); end
@@ -69,6 +73,7 @@ module Openapi3Parser
 
     def build_errors
       error_collection = Validation::ErrorCollection.new
+      return error_collection if nil_input?
       unless valid_type?
         error = Validation::Error.new(
           context.namespace, "Invalid type. #{validate_type}"
@@ -80,6 +85,10 @@ module Openapi3Parser
     end
 
     def build_valid_node
+      if nil_input?
+        return default.nil? ? nil : build_node(processed_input)
+      end
+
       unless valid_type?
         raise Openapi3Parser::Error,
               "Invalid type for #{context.stringify_namespace}. "\
@@ -108,7 +117,10 @@ module Openapi3Parser
     end
 
     def processed_input
-      @processed_input ||= process_input(context.input)
+      @processed_input ||= begin
+                             input = nil_input? ? default : context.input
+                             process_input(input)
+                           end
     end
 
     def process_input(input)
@@ -119,6 +131,10 @@ module Openapi3Parser
       input
     end
 
+    def default
+      nil
+    end
+
     def extension?(key)
       key.match(EXTENSION_REGEX)
     end

data/lib/openapi3_parser/node_factory/map.rb

@@ -34,6 +34,10 @@ module Openapi3Parser
       def build_map(data, _)
         data
       end
+
+      def default
+        {}
+      end
     end
   end
 end

data/lib/openapi3_parser/node_factory/object.rb

@@ -53,17 +53,15 @@ module Openapi3Parser
 
       def process_input(input)
         field_configs.each_with_object(input.dup) do |(field, config), memo|
-          next if !config.factory? || !memo[field]
+          next unless config.factory?
           next_context = context.next_namespace(field)
-          memo[field] = config.initialize_factory(
-            next_context, self
-          )
+          memo[field] = config.initialize_factory(next_context, self)
         end
       end
 
       def validate_input(error_collection)
         super(error_collection)
-        validator = Validator.new(processed_input, self)
+        validator = Validator.new(context.input, self)
         error_collection.tap { |ec| ec.append(*validator.errors) }
       end
 

data/lib/openapi3_parser/node_factory/object/node_builder.rb

@@ -16,10 +16,9 @@ module Openapi3Parser
           check_required_fields
           check_unexpected_fields
           check_fields_valid
-          data = input.each_with_object({}) do |(key, value), memo|
-            memo[key] = value.respond_to?(:node) ? value.node : value
+          input.each_with_object({}) do |(key, value), memo|
+            memo[key] = resolve_value(key, value)
           end
-          apply_defaults(data)
         end
 
         private
@@ -55,7 +54,8 @@ module Openapi3Parser
 
         def check_type_error(name, field_config)
           field_context = context.next_namespace(name)
-          error = field_config.input_type_error(input[name], factory)
+          input = context.input.nil? ? nil : context.input[name]
+          error = field_config.input_type_error(input, factory)
 
           return unless error
           raise Openapi3Parser::Error,
@@ -65,7 +65,7 @@ module Openapi3Parser
 
         def check_validation_errors(name, field_config)
           field_context = context.next_namespace(name)
-          errors = field_config.validation_errors(input[name], factory)
+          errors = field_config.validation_errors(field_context.input, factory)
 
           return unless errors.any?
           raise Openapi3Parser::Error,
@@ -73,10 +73,21 @@ module Openapi3Parser
                 "#{errors.join(', ')}"
         end
 
-        def apply_defaults(data)
+        def resolve_value(key, value)
           configs = factory.field_configs
-          configs.each_with_object(data) do |(name, field_config), _memo|
-            data[name] = field_config.default(factory) if data[name].nil?
+          return configs[key]&.default(factory) if value.nil?
+          default_value(configs[key], value)
+        end
+
+        def default_value(config, value)
+          resolved_value = value.respond_to?(:node) ? value.node : value
+
+          # let a field config default take precedence if value is a nil_input?
+          if value.respond_to?(:nil_input?) && value.nil_input?
+            default = config&.default(factory)
+            default.nil? ? resolved_value : default
+          else
+            resolved_value
           end
         end
       end

data/lib/openapi3_parser/nodes/array.rb

@@ -4,11 +4,19 @@ require "openapi3_parser/node/map"
 
 module Openapi3Parser
   module Nodes
+    # An array within a OpenAPI document.
+    # Very similar to a normal Ruby array, however this is read only and knows
+    # the context of where it sits in an OpenAPI document
+    #
+    # The contents of the data will be dependent on where this document is in
+    # the document hierachy.
     class Array
       include Enumerable
 
       attr_reader :node_data, :node_context
 
+      # @param [::Array] data     data used to populate this node
+      # @param [Context] context  The context of this node in the document
       def initialize(data, context)
         @node_data = data
         @node_context = context

data/lib/openapi3_parser/nodes/callback.rb

@@ -4,6 +4,7 @@ require "openapi3_parser/node/map"
 
 module Openapi3Parser
   module Nodes
+    # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callbackObject
     class Callback
       include Node::Map
     end

data/lib/openapi3_parser/nodes/components.rb

@@ -4,41 +4,53 @@ require "openapi3_parser/node/object"
 
 module Openapi3Parser
   module Nodes
+    # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject
     class Components
       include Node::Object
 
+      # @return [Map] a map of String: {Schema}[../Schema.html] objects
       def schemas
         node_data["schemas"]
       end
 
+      # @return [Map] a map of String: {Response}[./Response.html] objects
       def responses
         node_data["responses"]
       end
 
+      # @return [Map] a map of String: {Parameter}[./Parameter.html] objects
       def parameters
         node_data["parameters"]
       end
 
+      # @return [Map] a map of String: {Example}[../Example.html] objects
       def examples
         node_data["examples"]
       end
 
+      # @return [Map] a map of String: {RequestBody}[./RequestBody.html]
+      #         objects
       def request_bodies
         node_data["requestBodies"]
       end
 
+      # @return [Map] a map of String: {Header}[./Header.html] objects
       def headers
         node_data["headers"]
       end
 
+      # @return [Map] a map of String: {SecurityScheme}[./SecurityScheme.html]
+      #         objects
       def security_schemes
         node_data["securitySchemes"]
       end
 
+      # @return [Map] a map of String: {Link}[./Link.html] objects
       def links
         node_data["links"]
       end
 
+      # @return [Map] a map of String: {Callback}[./Callback.html] objects
       def callbacks
         node_data["callbacks"]
       end

data/lib/openapi3_parser/nodes/contact.rb

@@ -4,17 +4,21 @@ require "openapi3_parser/node/object"
 
 module Openapi3Parser
   module Nodes
+    # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#contactObject
     class Contact
       include Node::Object
 
+      # @return [String, nil]
       def name
         data["name"]
       end
 
+      # @return [String, nil]
       def url
         data["url"]
       end
 
+      # @return [String, nil]
       def email
         data["email"]
       end