open_api-loader 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bfec60cf6253d6d98d6e98dfb40314dbfb3922cc
+  data.tar.gz: 95607528b55ac357d5aad01e8d56b842a938f843
+SHA512:
+  metadata.gz: 98e1d24f7bd622ef43a98adef44fc56092de155462f4e7e1a1df96a9672f761c541435794b49a11850a4c8a82f72375efeb643e340f3a29895955131732aec83
+  data.tar.gz: a5c8e547e3f5e77102f84a0b893715f57d8ea1a847ef7c16fefc5bfff7ddff5db1491b07a991a65887b4a27f4ba2155fe98ddf6ec9e1df10da1749d44a5ec647

data/.codeclimate.yml

@@ -0,0 +1,15 @@
+---
+engines:
+  rubocop:
+    enabled: true
+  duplication:
+    enabled: true
+    config:
+      languages:
+        - ruby
+exclude_paths:
+- "benchmarks/**/*"
+- "spec/**/*"
+ratings:
+   paths:
+   - "lib/**/*"

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/*.gem
+/*.lock
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--warnings

data/.rubocop.yml

@@ -0,0 +1,28 @@
+---
+AllCops:
+  DisplayCopNames:    true
+  DisplayStyleGuide:  true
+  StyleGuideCopsOnly: true
+  TargetRubyVersion:  2.5
+
+Naming/FileName:
+  Exclude:
+    - "lib/open_api-loader.rb"
+
+Style/Alias:
+  Enabled: false
+
+Style/CaseEquality:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/DateTime:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/.travis.yml

@@ -0,0 +1,24 @@
+---
+language: ruby
+sudo: false
+cache: bundler
+bundler_args: --without benchmarks tools
+script: bundle exec rake
+rvm:
+  - 2.3.0
+  - 2.4.0
+  - 2.5.0
+  - ruby-head
+  - jruby-9.1.0.0
+  - rbx-3
+env:
+  global:
+    - JRUBY_OPTS='--dev -J-Xmx1024M'
+matrix:
+  allow_failures:
+    - rvm: rbx-3
+    - rvm: ruby-head
+    - rvm: jruby-head
+  include:
+    - rvm: jruby-head
+      before_install: gem install bundler --no-ri --no-rdoc

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.0.1] - [Unreleased]
+This is a first public release
+
+[Unreleased]: https://github.com/nepalez/open_api-loader

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "pry",        platform: :mri
+  gem "pry-byebug", platform: :mri
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018, Andrew Kozin (nepalez), andrew.kozin@gmail.com
+
+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,99 @@
+# OpenAPI::Loader
+
+Loads [OAS2][oas2] or [OAS3][oas3] scheme from YAML/JSON file(s), and converts it to OAS3 standard.
+
+<a href="https://evilmartians.com/">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+
+[![Gem Version][gem-badger]][gem]
+[![Build Status][travis-badger]][travis]
+[![Inline docs][inch-badger]][inch]
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'open_api-loader'
+```
+
+And then execute:
+
+```shell
+$ bundle
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install open_api-loader
+```
+
+## Usage
+
+```ruby
+require "open_api/loader"
+
+OpenAPI::Loader.call "path_to/source.yaml"
+# => { "openapi" => "3.0.0", ... }
+```
+
+It takes a filename of the specification (it should be in YAML or JSON), and returns a nested hash.
+
+The loader transforms the source in several ways:
+
+- reads the data,
+- collects all the [reference objects][ref] both local and remote (like `./models.yaml#/Pet` or `https://example.com/models#/Pet`), and includes them into the specification,
+- converts the specification from [OAS2][oas2] into [OAS3][oas3] standard,
+- removes the [components][components] because all links to its definitions are dereferenced,
+- denormalizes [servers][servers], [security][security], and [parameters][parameters] by moving shared definitions from both [root][root] and [path items][paths] right into the corresponding [operations][operations],
+- substitutes [server variables][server variables] into urls to provide "flat" servers list.
+
+You can skip the last 3 steps using option:
+
+```ruby
+OpenAPI::Loader.call "path_to/source.yaml", denormalize: false
+```
+
+## Development and Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nepalez/open_api-loader.
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+Before adding a PR, please run `rake` to run tests, style and documentation linters. You can also run `bin/console` for an interactive prompt [pry][pry] that will allow you to experiment.
+
+## TODO
+
+1. Check whether a [reference objects][ref] contain cycles
+2. Add script to run the loader from shell and save results to YAML/JSON file
+
+  ```shell
+  $ open_api load -s source.yaml -o output.yaml -d
+  ```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][license].
+
+[codeclimate-badger]: https://img.shields.io/codeclimate/github/nepalez/open_api-loader.svg?style=flat
+[codeclimate]: https://codeclimate.com/github/nepalez/open_api-loader
+[components]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject
+[gem-badger]: https://img.shields.io/gem/v/open_api-loader.svg?style=flat
+[gem]: https://rubygems.org/gems/open_api-loader
+[inch-badger]: http://inch-ci.org/github/nepalez/open_api-loader.svg
+[inch]: https://inch-ci.org/github/nepalez/open_api-loader
+[license]: https://opensource.org/licenses/MIT
+[oas2]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
+[oas3]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
+[operations]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject
+[parameters]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject
+[paths]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject
+[pry]: https://github.com/pry/pry
+[ref]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#referenceObject
+[root]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasObject
+[server variables]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverVariableObject
+[servers]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject
+[security]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securityRequirementObject
+[travis-badger]: https://img.shields.io/travis/nepalez/open_api-loader/master.svg?style=flat
+[travis]: https://travis-ci.org/nepalez/open_api-loader

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new :default
+
+task default: :spec do
+  system "rubocop"
+  system "inch --pedantic"
+end

data/bin/console

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "open_api"
+require "pry"
+
+Pry.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-loader.rb

@@ -0,0 +1 @@
+require_relative "open_api/loader"

data/lib/open_api/loader.rb

@@ -0,0 +1,44 @@
+require "constructor_shortcut"
+require "dry-initializer"
+require "json"
+require "yaml"
+require "uri"
+require "delegate"
+
+#
+# Namespace for gems dealing with OAS specifications
+#
+module OpenAPI
+  #
+  # Loads OAS specification from a file and converts it to OAS3 format
+  #
+  # @see OAS2
+  #   https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
+  # @see OAS3
+  #   https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
+  #
+  module Loader
+    module_function
+
+    require_relative "loader/ref"
+    require_relative "loader/reader"
+    require_relative "loader/collector"
+    require_relative "loader/translator"
+    require_relative "loader/denormalizer"
+
+    #
+    # Loads the specification from given file
+    #
+    # @param  [String]  filename The name of file containing a specification
+    # @option [Boolean] :denormalize Whether to denormalize specification
+    # @return [Hash] the specification
+    #
+    def call(filename, denormalize: true)
+      normalized = [Collector, Translator].inject(filename) do |output, item|
+        item.call(output)
+      end
+
+      denormalize ? Denormalizer.call(normalized) : normalized
+    end
+  end
+end

data/lib/open_api/loader/collector.rb

@@ -0,0 +1,61 @@
+module OpenAPI::Loader
+  #
+  # Collects the schema from given [#source] file
+  # - loads the schema (and recursively loads and caches all its "$ref" files)
+  # - hashifies the schema to provide nested hash with stringified keys
+  # - collects the schema from the cached sources
+  #
+  # Notice: The service is one-off because its instances cache variables:
+  #         `@uri` and `@path` (to provide absolute paths for `$ref`-s)
+  #         `@refs` (to minimize the number of remote file loading)
+  #
+  # TODO: For now it doesn't check that the graph of "$ref"-s has no cycles!
+  #
+  # @private
+  #
+  class Collector
+    extend Dry::Initializer
+    extend ConstructorShortcut[:call] # class-level .call
+
+    param  :source, proc(&:to_s)
+    option :uri,    default: -> { URI(source) if URI(source).absolute? }
+    option :path,   default: -> { Pathname(source) unless uri }
+
+    def call
+      build refs[""]
+    end
+
+    private
+
+    def refs
+      @refs ||= { "" => Reader.call(source) }
+    end
+
+    def build(data)
+      case data = deref(data)
+      when Hash  then data.each_with_object({}) { |(k, v), o| o[k] = build(v) }
+      when Array then data.map { |item| build(item) }
+      else data
+      end
+    end
+
+    def deref(data)
+      ref = data["$ref"] if data.is_a? Hash
+      return data unless ref
+
+      pointer = Ref.new(ref)
+      source  = remote(pointer.uri.to_s)
+      pointer.fetch_from(source)
+    end
+
+    def remote(value)
+      refs[value] ||= Collector.call absolute_path(value)
+    end
+
+    def absolute_path(value)
+      return value if URI(value).absolute?
+      return value if Pathname(value).absolute?
+      uri&.merge(value) || path.dirname.join(value)
+    end
+  end
+end

data/lib/open_api/loader/denormalizer.rb

@@ -0,0 +1,27 @@
+module OpenAPI::Loader
+  #
+  # Denormalizes OAS3 `parameters`, `servers`, and `security`
+  # by moving them from OpenAPI root and Path objects
+  # right into the corresponding Operation objects.
+  #
+  # @private
+  #
+  class Denormalizer
+    require_relative "denormalizer/parameters"
+    require_relative "denormalizer/security"
+    require_relative "denormalizer/servers"
+    require_relative "denormalizer/variables"
+
+    extend Dry::Initializer
+    extend ConstructorShortcut[:call] # class-level .call
+
+    param :source
+
+    def call
+      WRAPPERS.each { |wrapper| wrapper.new(source).call }
+      source
+    end
+
+    WRAPPERS = [Parameters, Security, Servers, Variables].freeze
+  end
+end

data/lib/open_api/loader/denormalizer/parameters.rb

@@ -0,0 +1,46 @@
+class OpenAPI::Loader::Denormalizer
+  #
+  # Denormalizes all the 'parameters' definitions
+  # by moving them from the root OpenAPI object and path objects
+  # right into the corresponding operation objects.
+  #
+  # @private
+  #
+  class Parameters < SimpleDelegator
+    def call
+      root_params = extract_from(self)
+      paths.each do |path|
+        path_params = extract_from(path, root_params)
+        operations(path).each do |operation|
+          parameters = extract_from(operation, path_params)
+          operation["parameters"] = parameters if parameters.any?
+        end
+      end
+    end
+
+    private
+
+    def paths
+      Enumerator.new do |yielder|
+        fetch("paths", {}).each_value do |path|
+          yielder << path if path.is_a? Hash
+        end
+      end
+    end
+
+    def operations(path)
+      Enumerator.new do |yielder|
+        path.each_value { |item| yielder << item if item.is_a? Hash }
+      end
+    end
+
+    def extract_from(data, default = [])
+      custom = Array(data.delete("parameters")).select do |item|
+        item.is_a?(Hash) && item["name"]
+      end
+
+      custom_names = custom.map { |item| item["name"] }
+      default.reject { |item| custom_names.include? item["name"] } + custom
+    end
+  end
+end