openapi3_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3c7e2585cb3bbdbda459519eb7e264dfd89f5745
+  data.tar.gz: 4fdbb4b547e626e1b0ba5f502b93107638af3655
+SHA512:
+  metadata.gz: 498d2043a338970c66ef9d14590adb34ec2f7b65e751985f8d12a8c9506d63e09a9840e7521b00a953000af1e286917147fb4507be29f68a5c047aa9f124f7d8
+  data.tar.gz: 7fb4d6b168b514fa01056fa5be0026551ad02e0e47506e99516b14b290e450c0940031e82fc38bdc0f4c5d137d98d3a621f28d42bd6e5923f335a7c31255796e

data/.gitignore

@@ -0,0 +1 @@
+/Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,9 @@
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+Metrics/MethodLength:
+  Max: 30
+Documentation:
+  Enabled: false
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+sudo: false
+rvm:
+- 2.3.1

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Kevin Dew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,32 @@
+# OpenAPI 3 Parser
+
+[![Build Status](https://travis-ci.org/kevindew/openapi_parser.svg?branch=master)](https://travis-ci.org/kevindew/openapi_parser)
+
+
+This is a parser/validator for [Open API 3][openapi-3] built in Ruby.
+
+Example usage:
+
+```
+require "openapi3_parser"
+
+document = Openapi3Parser.load_file("path/to/example.yaml")
+
+# check whether document is valid
+document.valid?
+
+# traverse document
+document.paths["/"]
+```
+
+[openapi-3]: https://github.com/OAI/OpenAPI-Specification
+
+## Status
+
+This is currently a work in progress and will remain so until it reaches 1.0.
+
+See [TODO](TODO.md) for details of the roadmap there.
+
+## Licence
+
+[MIT License](LICENCE)

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %I[rubocop spec]

data/TODO.md

@@ -0,0 +1,30 @@
+# Todo
+
+These are the steps defined to reach 1.0. Assistance is very welcome.
+
+- [ ] Handle mutually exclusive fields
+- [ ] Refactor the various NodeFactory modules to be a less confusing
+      hierachical structure. Consider having factories subclass instead of use
+      mixin
+- [ ] Decouple Document class for the source file. Consider a source file class
+      instead
+- [ ] Validate that a reference creates the type of node that is expected in
+      a context
+- [ ] Allow opening of references from additional files
+- [ ] Allow opening of openapi documents by URL
+- [ ] Support references by URL, consider option to limit behaviour
+- [ ] Support converting CommonMark to HTML
+- [ ] Reach parity with OpenAPI specification for validation
+- [ ] Consider a lenient mode for a document to only have to comply with type
+      based validation
+- [ ] Improve test coverage
+- [ ] Publish documentation of the interface through the structure
+- [ ] Consider a resolved context class for representing context with a node
+      that can handle scenarios where a node is represented by both a reference
+      and resolved context
+- [ ] Create error classes for various scenarios
+- [ ] Associate/resolve operation id / operation references
+- [ ] Do something to model expressions
+- [ ] Improve the modelling of namespace
+- [ ] Set up nicer string representations of key classes to help them be
+      debugged

data/lib/openapi3_parser.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/error"
+require "openapi3_parser/document"
+
+require "yaml"
+require "json"
+
+module Openapi3Parser
+  def self.load(input)
+    # working_directory ||= if input.respond_to?(:read)
+    #                         File.dirname(input)
+    #                       else
+    #                         Dir.pwd
+    #                       end
+
+    Document.new(parse_input(input))
+  end
+
+  def self.load_file(path)
+    file = File.open(path)
+    load(file)
+  end
+
+  def self.parse_input(input)
+    return input if input.respond_to?(:keys)
+
+    extension = input.respond_to?(:extname) ? input.extname : nil
+    contents = input.respond_to?(:read) ? input.read : input
+
+    if extension == ".json" || contents.strip[0] == "{"
+      JSON.parse(contents)
+    else
+      YAML.safe_load(contents, [], [], true)
+    end
+  end
+
+  private_class_method :parse_input
+end

data/lib/openapi3_parser/context.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Openapi3Parser
+  class Context
+    attr_reader :input, :namespace, :document, :parent
+
+    def initialize(input:, namespace: [], document:, parent: nil)
+      @input = input
+      @namespace = namespace.freeze
+      @document = document
+      @parent = parent
+    end
+
+    def self.root(input, document)
+      new(input: input, document: document)
+    end
+
+    def stringify_namespace
+      return "root" if namespace.empty?
+      namespace
+        .map { |i| i.include?("/") ? %("#{i}") : i }
+        .join("/")
+    end
+
+    def next_namespace(segment, next_input = nil)
+      next_input ||= input[segment]
+      self.class.new(
+        input: next_input,
+        namespace: namespace + [segment],
+        document: document,
+        parent: self
+      )
+    end
+
+    def resolve_reference
+      document.resolve_reference(input["$ref"]) do |resolved_input, namespace|
+        # @TODO track reference for cyclic depenendies
+        next_context = resolved_reference(resolved_input, namespace)
+        yield(next_context)
+      end
+    end
+
+    private
+
+    def resolved_reference(input, namespace)
+      self.class.new(
+        input: input,
+        namespace: namespace,
+        document: document,
+        parent: parent
+      )
+    end
+  end
+end

data/lib/openapi3_parser/document.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/context"
+require "openapi3_parser/error"
+require "openapi3_parser/node_factories/openapi"
+
+require "forwardable"
+
+module Openapi3Parser
+  class Document
+    extend Forwardable
+
+    attr_reader :input
+
+    def_delegators :factory, :valid?, :errors
+    def_delegators :root, :openapi, :info, :servers, :paths, :components,
+                   :security, :tags, :external_docs, :extension, :[], :each
+
+    def initialize(input)
+      @input = input
+    end
+
+    def root
+      factory.node
+    end
+
+    def resolve_reference(reference)
+      if reference[0..1] != "#/"
+        raise Error, "Only anchor references are currently supported"
+      end
+
+      parts = reference.split("/").drop(1).map do |field|
+        CGI.unescape(field.gsub("+", "%20"))
+      end
+
+      result = input.dig(*parts)
+      raise Error, "Could not resolve reference #{reference}" unless result
+
+      yield(result, parts)
+    end
+
+    private
+
+    def factory
+      @factory ||= NodeFactories::Openapi.new(Context.root(input, self))
+    end
+  end
+end

data/lib/openapi3_parser/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Openapi3Parser
+  class Error < ::RuntimeError; end
+end

data/lib/openapi3_parser/fields/map.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/error"
+
+module Openapi3Parser
+  module Fields
+    class Map
+      private_class_method :new
+
+      def initialize(input, context, value_type, key_format)
+        @input = input
+        @context = context
+        @value_type = value_type
+        @key_format = key_format
+      end
+
+      def self.call(
+        input,
+        context,
+        value_type: Hash,
+        key_format: nil,
+        &block
+      )
+        new(input, context, value_type, key_format).call(&block)
+      end
+
+      def self.reference_input(
+        input,
+        context,
+        value_type: Hash,
+        key_format: nil,
+        &block
+      )
+        call(
+          input, context, value_type: value_type, key_format: key_format
+        ) do |field_input, field_context|
+          field_context.possible_reference(field_input, &block)
+        end
+      end
+
+      def call(&block)
+        validate_keys
+        validate_values
+
+        input.each_with_object({}) do |(key, value), memo|
+          memo[key] = if block
+                        yield(value, context.next_namespace(key), key)
+                      else
+                        value
+                      end
+        end
+      end
+
+      private
+
+      attr_reader :input, :context, :value_type, :key_format
+
+      def validate_keys
+        return unless key_format
+        invalid_keys = input.keys.reject { |key| key =~ key_format }
+        return if invalid_keys.empty?
+
+        raise Openapi3Parser::Error, "Invalid field names for "\
+          "#{context.stringify_namespace}: #{invalid_keys.join(', ')}"
+      end
+
+      def validate_values
+        return unless value_type
+        invalid = input.reject do |key, value|
+          if value_type.is_a?(Proc)
+            value.call(value, key)
+          else
+            value.is_a?(value_type)
+          end
+        end
+        return if invalid.empty?
+
+        raise Openapi3Parser::Error, "Unexpected type for "\
+          "#{context.stringify_namespace}: #{invalid.keys.join(', ')}"
+      end
+    end
+  end
+end

data/lib/openapi3_parser/node.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/node/field_config"
+
+module Openapi3Parser
+  module Node
+    module ClassMethods
+      def field(name, **options)
+        @field_configs ||= {}
+        @field_configs[name] = FieldConfig.new(options)
+      end
+
+      def field_configs
+        @field_configs || {}
+      end
+
+      def allow_extensions
+        @allow_extensions = true
+      end
+
+      def disallow_extensions
+        @allow_extensions = false
+      end
+
+      def allowed_extensions?
+        @allow_extensions == true
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    EXTENSION_REGEX = /^x-(.*)/
+
+    attr_reader :input, :context, :fields
+
+    def initialize(input, context)
+      @input = input
+      @context = context
+      @fields = build_fields(input)
+    end
+
+    def [](value)
+      fields[value]
+    end
+
+    def extension(value)
+      fields["x-#{value}"]
+    end
+
+    private
+
+    def build_fields(input)
+      check_for_unexpected_fields(input)
+      create_fields(input)
+    end
+
+    def check_for_unexpected_fields(input)
+      allowed_fields = field_configs.keys
+      remaining_fields = input.keys - allowed_fields
+      return if remaining_fields.empty?
+
+      if allowed_extensions?
+        remaining_fields.reject! { |key| key =~ EXTENSION_REGEX }
+      end
+
+      return if remaining_fields.empty?
+      raise Error,
+            "Unexpected attributes for #{context.stringify_namespace}: "\
+            "#{remaining_fields.join(', ')}"
+    end
+
+    def create_fields(input)
+      check_required(input)
+      check_types(input)
+      fields = field_configs.each_with_object({}) do |(field, config), memo|
+        next_context = context.next_namespace(field)
+        memo[field] = config.build(input[field], self, next_context)
+      end
+      extensions = input.select { |(k, _)| k =~ EXTENSION_REGEX }
+      fields.merge(extensions)
+    end
+
+    def check_required(input)
+      missing = field_configs.reject do |field, config|
+        config.valid_presence?(input[field])
+      end
+
+      return if missing.empty?
+      raise Error,
+            "Missing required fields for #{context.stringify_namespace}: "\
+              "#{missing.keys}"
+    end
+
+    def check_types(input)
+      invalid = field_configs.reject do |field, config|
+        config.valid_input_type?(input[field], self)
+      end
+
+      return if invalid.empty?
+      raise Error,
+            "Invalid fields for #{context.stringify_namespace}: "\
+              "#{invalid.keys}"
+    end
+
+    def allowed_extensions?
+      self.class.allowed_extensions?
+    end
+
+    def field_configs
+      self.class.field_configs || {}
+    end
+  end
+end