open_api_parser 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7ebb287c98a211acf8ad3a00f41e6d217f4f18e5
+  data.tar.gz: 8ab60127e9539f5a2d62294c4a48e577713c8657
+SHA512:
+  metadata.gz: 6b3bebdfc00a16569e432169aa403bf01cba7ef86cac9a23a2670be109116612e7041225b9f891efb96b4c5495fc7a042138587a1896c1cc1297194b30fb7503
+  data.tar.gz: ea03826b7a5996f341e7958ed203390979c87ce2349056cd00f0479f9bff147353797226c85dbdae3449685cdc8f4dc65fe8040ef32c0dd533d86919b7e34be3

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/tags
+/.ruby-version
+/open_api_parser*.gem

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.13.1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+* Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Braintree, a division of PayPal, Inc.
+
+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,116 @@
+# OpenApiParser
+
+A gem for parsing Open API specifications.
+
+## Usage
+
+First, resolve a specification given an absolute file path.
+
+```ruby
+specification = OpenApiParser::Specification.resolve("/path/to/my/specification.yaml")
+```
+
+When you `resolve` your file, all references will be expanded and inlined. The fully resolved specification will be validated against the Open API V2 meta schema. If you'd like to prevent meta schema validation, you can provide an option to do so.
+
+```ruby
+specification = OpenApiParser::Specification.resolve("/path/to/my/specification.yaml", validate_meta_schema: false)
+```
+
+If you'd rather instantiate a specification with a _fully resolved_ ruby hash, you can do so by directly instantiating an `OpenApiParser::Specification::Root`.
+
+```
+OpenApiParser::Specification::Root.new({...})
+```
+
+### Reference resolution
+
+`OpenApiParser::Specification.resolve` will fully resolve the provided Open API specification by inlining all [JSON References](https://tools.ietf.org/id/draft-pbryan-zyp-json-ref-03.html). Two types of references are allowed:
+
+* [JSON Pointers](https://tools.ietf.org/html/rfc6901)
+* JSON References to files
+
+Pointers are resolved from the root of the document in which they appear. File references are resolved relative to the file in which they appear. Here's an example of each:
+
+```yaml
+definitions:
+  person:
+    type: object
+    properties:
+      name:
+        type: string
+      age:
+        type: integer
+
+info:
+  person:
+    $ref: "/definitions/person"
+  other:
+    $ref: "file:another/file.yaml"
+```
+
+For more information, see the specs.
+
+### Endpoints
+
+With a resolved schema, you can access the information for an endpoint given a path and an HTTP verb.
+
+```ruby
+endpoint = specification.endpoint("/animals", "post")
+```
+
+With an endpoint, you can get access to JSON schema representations of the body, headers, path, query params and response body and headers defined in your Open API specification. You can use these to validate input using any existing JSON Schema library. We recommend [JsonSchema](https://github.com/brandur/json_schema).
+
+```ruby
+endpoint.body_schema
+# => {...}
+
+endpoint.header_schema
+# => {...}
+
+endpoint.path_schema
+# => {...}
+
+endpoint.query_schema
+# => {...}
+
+endpoint.response_body_schema(201)
+# => {...}
+
+endpoint.response_header_schema(201)
+# => {...}
+```
+
+You can also use the endpoint to transform user input into json that can be validated against the schemas generated in the previous examples.
+
+```ruby
+endpoint.header_json(request_headers_as_hash)
+# => {...}
+
+endpoint.path_json("/animals/123?query=param")
+# => {...}
+
+endpoint.query_json(request_query_params_as_hash)
+# => {...}
+```
+
+For more information, see the specs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'open_api_parser'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install open_api_parser
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "open_api_parser"
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/lib/open_api_parser/document.rb

@@ -0,0 +1,64 @@
+module OpenApiParser
+  class Document
+    def self.resolve(path, file_cache=OpenApiParser::FileCache.new)
+      file_cache.get(path) do
+        content = YAML.load_file(path)
+        Document.new(path, content, file_cache).resolve
+      end
+    end
+
+    def initialize(path, content, file_cache)
+      @path = path
+      @content = content
+      @file_cache = file_cache
+    end
+
+    def resolve
+      deeply_expand_refs(@content)
+    end
+
+    private
+
+    def deeply_expand_refs(fragment)
+      fragment = expand_refs(fragment)
+
+      if fragment.is_a?(Hash)
+        fragment.reduce({}) do |hash, (k, v)|
+          hash.merge(k => deeply_expand_refs(v))
+        end
+      elsif fragment.is_a?(Array)
+        fragment.map { |e| deeply_expand_refs(e) }
+      else
+        fragment
+      end
+    end
+
+    def expand_refs(fragment)
+      if fragment.is_a?(Hash) && fragment.has_key?("$ref")
+        ref = fragment["$ref"]
+
+        if ref =~ /\Afile:/
+          expand_file(ref)
+        else
+          expand_pointer(ref)
+        end
+      else
+        fragment
+      end
+    end
+
+    def expand_file(ref)
+      relative_path = ref.split(":").last
+      absolute_path = File.expand_path(File.join("..", relative_path), @path)
+
+      Document.resolve(absolute_path, @file_cache)
+    end
+
+    def expand_pointer(ref)
+      pointer = OpenApiParser::Pointer.new(ref)
+      fragment = pointer.resolve(@content)
+
+      expand_refs(fragment)
+    end
+  end
+end

data/lib/open_api_parser/file_cache.rb

@@ -0,0 +1,15 @@
+module OpenApiParser
+  class FileCache
+    def initialize
+      @cache = {}
+    end
+
+    def get(key, &block)
+      return @cache[key] if @cache.has_key?(key)
+
+      block.call.tap do |result|
+        @cache[key] = result
+      end
+    end
+  end
+end

data/lib/open_api_parser/pointer.rb

@@ -0,0 +1,45 @@
+module OpenApiParser
+  class Pointer
+    def initialize(raw_pointer)
+      @raw_pointer = raw_pointer
+    end
+
+    def resolve(document)
+      return document if escaped_pointer == ""
+
+      tokens.reduce(document) do |nested_doc, token|
+        nested_doc.fetch(token)
+      end
+    end
+
+    private
+
+    def escaped_pointer
+      if @raw_pointer.start_with?("#")
+        URI.decode(@raw_pointer[1..-1])
+      else
+        @raw_pointer
+      end
+    end
+
+    def parse_token(token)
+      if token =~ /\A\d+\z/
+        token.to_i
+      else
+        token.gsub("~0", "~").gsub("~1", "/")
+      end
+    end
+
+    def tokens
+      tokens = escaped_pointer[1..-1].split("/")
+
+      if @raw_pointer.end_with?("/")
+        tokens << ""
+      end
+
+      tokens.map do |token|
+        parse_token(token)
+      end
+    end
+  end
+end

data/lib/open_api_parser/specification/endpoint.rb

@@ -0,0 +1,161 @@
+module OpenApiParser
+  module Specification
+    class Endpoint
+      RESERVED_PARAMETER_KEYS = [
+        "name",
+        "in",
+        "description",
+        "required"
+      ]
+
+      attr_reader :raw
+
+      def initialize(path, method, raw)
+        @path = path
+        @method = method
+        @raw = raw
+      end
+
+      def body_schema
+        body_param = parameters.detect { |param| param["in"] == "body" }
+        return restrictive_schema if body_param.nil?
+
+        body_param["schema"]
+      end
+
+      def header_schema
+        @header_schema ||= begin
+         schema = parameter_schema(permissive_schema, "header")
+
+         schema.tap do |schema|
+           schema["properties"] = schema["properties"].reduce({}) do |props, (k, v)|
+             props.merge(headerize(k) => v)
+           end
+         end
+        end
+      end
+
+      def path_schema
+        @path_schema ||= parameter_schema(restrictive_schema, "path")
+      end
+
+      def query_schema
+        @query_schema ||= parameter_schema(restrictive_schema, "query")
+      end
+
+      def response_body_schema(status)
+        response = response_from_status(status)
+        return restrictive_schema if response.nil?
+
+        response["schema"]
+      end
+
+      def response_header_schema(status)
+        response = response_from_status(status)
+        return permissive_schema if response.nil?
+
+        header_properties = response.fetch("headers", {}).reduce({}) do |props, (k, v)|
+          props.merge(headerize(k) => v)
+        end
+
+        permissive_schema.tap do |schema|
+          schema["properties"] = header_properties
+          schema["required"] = header_properties.keys
+        end
+      end
+
+      def header_json(headers)
+        schema = header_schema
+
+        headers.reduce({}) do |json, (k, v)|
+          json.merge(json_entry(schema, headerize(k), v))
+        end
+      end
+
+      def path_json(request_path)
+        pattern = Regexp.new(@path.gsub(/\{([^}]+)\}/, '(?<\1>[^/]+)'))
+        match = pattern.match(request_path.gsub(/\..+\z/, ""))
+        schema = path_schema
+
+        match.names.reduce({}) do |json, name|
+          json.merge(json_entry(schema, name, match[name]))
+        end
+      end
+
+      def query_json(query_params)
+        schema = query_schema
+
+        query_params.reduce({}) do |json, (k, v)|
+          json.merge(json_entry(schema, k, v))
+        end
+      end
+
+      private
+
+      def permissive_schema
+        {
+          "additionalProperties" => true,
+          "properties" => {}
+        }
+      end
+
+      def restrictive_schema
+        {
+          "additionalProperties" => false,
+          "properties" => {}
+        }
+      end
+
+      def headerize(name)
+        name.gsub("-", "_").upcase
+      end
+
+      def json_entry(schema, name, value)
+        properties = schema["properties"]
+
+        if properties.has_key?(name) && properties[name]["type"] == "integer" && value =~ /\A[0-9]+\z/
+          {name => value.to_i}
+        else
+          {name => value}
+        end
+      end
+
+      def parameters
+        @raw.fetch("parameters", [])
+      end
+
+      def parameter_schema(empty_schema, type)
+        type_params = parameters.select { |param| param["in"] == type }
+        return empty_schema if type_params.empty?
+
+        properties = type_params.reduce({}) do |schema, param|
+          schema_value = param.clone.delete_if do |k, v|
+            RESERVED_PARAMETER_KEYS.include?(k)
+          end
+
+          schema.merge(param["name"] => schema_value)
+        end
+
+        type_schema = empty_schema.merge("properties" => properties)
+
+        required_params = type_params.select { |param| param["required"] == true }.map { |param| param["name"] }
+
+        if required_params.any?
+          type_schema["required"] = required_params
+        end
+
+        type_schema
+      end
+
+      def response_from_status(status)
+        entry = @raw.fetch("responses", {}).detect do |k, v|
+          k.to_s == status.to_s
+        end
+
+        return @raw.fetch("responses", {})["default"] if entry.nil?
+
+        entry.last
+      end
+    end
+  end
+end

data/lib/open_api_parser/specification/root.rb

@@ -0,0 +1,40 @@
+module OpenApiParser
+  module Specification
+    class Root
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+      end
+
+      def endpoint(path, request_method)
+        uri = URI.parse(path)
+        requested_path = uri.path.gsub(/\..+\z/, "")
+
+        path_details = @raw["paths"].detect do |path_name, path|
+          requested_path =~ to_pattern(path_name)
+        end
+        return nil if path_details.nil?
+
+        path = path_details.last
+
+        method_details = path.detect do |method, schema|
+          method.to_s == request_method.downcase
+        end
+        return nil if method_details.nil?
+
+        Endpoint.new(path_details.first, method_details.first, method_details.last)
+      end
+
+      def to_json
+        JSON.generate(@raw)
+      end
+
+      private
+
+      def to_pattern(path_name)
+        Regexp.new("\\A" + path_name.gsub(/\{[^}]+\}/, "[^/]+") + "\\z")
+      end
+    end
+  end
+end

data/lib/open_api_parser/specification.rb

@@ -0,0 +1,16 @@
+module OpenApiParser
+  module Specification
+    META_SCHEMA_PATH = File.expand_path("../../../resources/swagger_meta_schema.json", __FILE__)
+
+    def self.resolve(path, validate_meta_schema: true)
+      raw_specification = Document.resolve(path)
+
+      if validate_meta_schema
+        meta_schema = JSON.parse(File.read(META_SCHEMA_PATH))
+        JsonSchema.parse!(meta_schema).validate!(raw_specification)
+      end
+
+      OpenApiParser::Specification::Root.new(raw_specification)
+    end
+  end
+end

data/lib/open_api_parser/version.rb

@@ -0,0 +1,3 @@
+module OpenApiParser
+  VERSION = "1.0.0"
+end

data/lib/open_api_parser.rb

@@ -0,0 +1,13 @@
+require "json"
+require "uri"
+require "yaml"
+
+require "json_schema"
+
+require "open_api_parser/document"
+require "open_api_parser/file_cache"
+require "open_api_parser/pointer"
+require "open_api_parser/specification"
+require "open_api_parser/specification/endpoint"
+require "open_api_parser/specification/root"
+require "open_api_parser/version"

data/open_api_parser.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'open_api_parser/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "open_api_parser"
+  spec.version       = OpenApiParser::VERSION
+  spec.authors       = ["Braintree"]
+  spec.email         = ["code@getbraintree.com"]
+
+  spec.summary       = %q{A parser for Open API specifications}
+  spec.description   = %q{A parser for Open API specifications}
+  spec.homepage      = "https://github.com/braintree/open_api_parser"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "json_schema", "~> 0.13.3"
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end