open-api 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0d0cd8c8411ef75344e1c82168450f2380e44626
-  data.tar.gz: 38a76fa2758c2d2c28106c6639b6c01e6ebc5f5a
+  metadata.gz: 4058f027c10a1877a4d58919f0f919f282c443a5
+  data.tar.gz: 1cca862076eb32844b8dee56d2757dbd545efcd7
 SHA512:
-  metadata.gz: da87e21f7639792c895297f901274fb1560d88cc57bf3a171baaf28576718b77becfb98dfce9094851190d47357971220d435ec750799ad5352483e181f54cca
-  data.tar.gz: 458bc117fd7c642d422fd518ede8697b529aae571abdccb402040d2f3de02ac36c59f5259dd89a6b15ad47dade93751ae214250d93a1b973d6178856297312b9
+  metadata.gz: db59e78681bd7d0826fe61cf6623adf3675494f0e1a743f74a1edf8da095dd50f04cf5eec5ae373238006dc7ab1ce7d67451c9ae0dab4cf2d26870853985e60d
+  data.tar.gz: 60c02fa2366b4db2fd6412dd928e264e34e4b86a6b128ca2cfe0ac2d7f114ab6dc5a716c6fbd92865e91b8de8cfdc34db15da79bcc4fad833a14f4ba158a6fc0

data/README.md

@@ -0,0 +1,143 @@
+# open-api
+
+**A flexible, inline [OpenAPI](https://github.com/OAI/OpenAPI-Specification) documentation solution
+for your Rails-based REST API.**
+
+[OpenAPI](https://github.com/OAI/OpenAPI-Specification) (formerly Swagger) is a popular,
+JSON-based, language-agnostic standard for documenting a REST API.  It's quickly becoming the
+industry-leading appraoch for describing REST API's of all shapes and sizes.
+
+However, maintaining your own lengthy, stand-alone JSON documentation alongside your Rails API
+source code is tedious and error-prone process to say the least.  Here's why using the open-api gem
+is better:
+
++ The open-api gem merges documentation details you provide with API metadata supplied by the
+  Rails framework itself, reducing your documentation effort and helping to maintain the accuracy
+  of your documentation over time.
++ Your API documentation details live inline right alongside your API source code.  As your API
+  changes, locating and updating documentation affected by those changes becomes a far easier task.
++ Metadata inheritance and intelligent merging rules miminize the need to document anything more
+  than once, further reducing the development and maintenance burden associated with your API
+  documentation.
++ Metadata that's not directly interpreted by open-api is generally passed through to the output
+  JSON intact.  As the OpenAPI standard evolves, you won't be limited to using OpenAPI features the
+  gem was explicitly written to manage.
+
+## Table of Contents
+
+## Installation
+
+Put this in your Gemfile:
+
+``` ruby
+gem 'open-api'
+```
+## Configuration
+
+Configuration for the open-api gem is performed using an `open_api.rb` initializer in your
+`config/initializers` subdirectory.  A sample initializer follows:
+
+``` ruby
+OpenApi.configure do |config|
+
+  # Default base path(s), used to scan Rails routes for API endpoints.
+  config.base_paths = ['/widget-api/v1']
+
+  # General information about your API.
+  config.info = {
+      title: 'Acme Widget API',
+      description: "Documentation of the Acme's Widget API service",
+      version: '1.0.0',
+      terms_of_service: 'https://www.acme.com/widget-api/terms_of_service',
+
+      contact: {
+          name: 'Acme Corporation API Team',
+          url: 'http://www.acme.com/widget-api',
+          email: 'widget-api-support@acme.com'
+      },
+
+      license: {
+          name: 'Apache 2.0',
+          url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+      }
+  }
+
+  # Default output file path for your generated Open API JSON document.
+  config.output_file_path = Rails.root.join('apidoc', 'api-docs.json')
+end
+```
+
+For details regarding content you may include in the "info" section of your API documentation, see
+the[OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#infoObject).
+
+
+## Describing Endpoints
+
+### Controller-Level Metadata
+
+Controller-level metadata is Open API documentation metadata common to all endpoints for a
+controller, as well as any endpoints associated with that controller's subclasses.  Below is an
+example of how characteristics common to all endpoints in an API might be defined in a base API
+controller:
+``` ruby
+    class BaseApiController < ActionController::Base
+
+      # Include once in your base API controller class
+      include OpenApi::Controller
+
+      open_api_controller \
+          query_string: {
+            access_token: {
+              type: :string,
+              description: 'OAuth 2 access token query parameter',
+              required: false
+            }
+          },
+          headers: {
+              'X-Access-Token' => {
+                type: :string,
+                description: 'OAuth 2 access token HTTP header',
+                required: false
+              }
+          },
+          responses: {
+              200 => { description: 'Successful' },
+              401 => { description: 'Invalid request' },
+              403 => { description: 'Not authorized' }
+          }
+```
+
+Another common use of `api_controller` is to define a tag for all endpoints associated with a
+specific controller:
+``` ruby
+class WidgetController < BaseApiController
+
+  open_api_controller \
+    tag: {
+        name: 'Widgets',
+        description: 'Manage the widgets associated with your user account'
+    }
+```
+Note that, in the example above, any documentation metadata specified for `BaseApiController` is
+inherited for endpoints defined in `WidgetController`.  If the same metadata key is defined for both
+controllers, the child controller's metadata will override the superclass' for that key.
+
+Note also that the process of merging metadata in a class hierarchy isn't as simple as doing a
+top-level merge or recursive merge for metadata belonging to the classes in that hierarchy.  The
+merge process can vary depending on the sort of metadata being merged.  For example, when two query
+string parameter lists are merged amongst classes in a hierarchy, the query string entries will be
+merged recursively.  This might, for example, allow a description to be amended in a child
+controller to a query string parameter defined in a base controller.  For other metadata, the
+collection value of a parent controller might be entirely replaced.
+
+
+## Describing Objects
+## Generating Documentation
+
+Generate OpenApi (Swagger) JSON by running the following:
+
+    rake open_api:docs
+
+Optionally, you may specify the base path and output file:
+
+    rake open_api:docs[/api/v1,/home/myhome/api-v1.json]

data/lib/open-api/controller.rb

@@ -0,0 +1,9 @@
+module OpenApi
+  module Controller
+    def self.included(base)
+      base.send(:include, OpenApi::Endpoints::Controller)
+      base.send(:include, OpenApi::Objects::Controller)
+      base.send(:include, OpenApi::Tags::Controller)
+    end
+  end
+end

data/lib/open-api/endpoints.rb

@@ -0,0 +1,173 @@
+module OpenApi
+  class Endpoints
+    class << self
+      METADATA_MERGE = {
+          tags: (lambda do |tags, merge_tags|
+            tags ||= {}
+            return tags if merge_tags.nil?
+            fail 'Expected tags as an Array!' unless merge_tags.is_a?(Array)
+            tags + merge_tags
+          end),
+          headers: (lambda do |headers, merge_headers, opts|
+            OpenApi::Utils.verify_and_merge_hash(headers, merge_headers, 'header parameters', opts)
+          end),
+          path_params: (lambda do |path_params, merge_path_params, opts|
+            OpenApi::Utils.verify_and_merge_hash(path_params, merge_path_params, 'path parameters',
+                opts)
+          end),
+          query_string: (lambda do |query_string, merge_query_string, opts|
+            OpenApi::Utils.verify_and_merge_hash(query_string, merge_query_string,
+                'query string parameters', opts)
+          end),
+          form_data: (lambda do |form_data, merge_form_data, opts|
+            OpenApi::Utils.verify_and_merge_hash(form_data, merge_form_data, 'form data parameters',
+                opts)
+          end),
+          body: (lambda do |body_data, merge_body_data, opts|
+            OpenApi::Utils.verify_and_merge_hash(body_data, merge_body_data, 'body', opts)
+          end),
+          responses: (lambda do |responses, merge_responses, opts|
+            merge_responses = Hash[(merge_responses.map do |key, hash|
+              fail "Invalid response code #{key}" if key.to_s != key.to_i.to_s
+              [key.to_i, hash]
+            end)]
+            OpenApi::Utils.verify_and_merge_hash(responses, merge_responses, 'responses', opts)
+          end)
+      }
+
+      def merge_metadata(metadata, merge_metadata, opts = {})
+        if (body_value = merge_metadata[:body]).respond_to?(:to_sym)
+          merge_metadata = merge_metadata.merge(body: { schema: { :'$ref' => body_value.to_sym } })
+        end
+        if merge_metadata.include?(:children)
+          merge_metadata = merge_metadata.reject { |k, _v| k == :children }
+        end
+        OpenApi::Utils.merge_hash(metadata, merge_metadata, opts.merge(merge_by: METADATA_MERGE))
+      end
+
+      def relative_path(path, base_path)
+        return path if path.blank? || base_path.blank?
+        relative_path = path[base_path.length..-1]
+        relative_path = "/#{relative_path}" unless relative_path.starts_with?('/')
+        relative_path
+      end
+
+      def verb_key(route_wrapper)
+        route_wrapper.verb.to_s.downcase
+      end
+
+      def find_matching_routes(base_path, opts = {})
+        path_filter = opts[:path_filter]
+        if path_filter.is_a?(String) && !path_filter.starts_with?('/')
+          path_filter = "/#{path_filter}"
+        end
+        matching_routes = []
+        Rails.application.routes.routes.each do |route|
+          route_wrapper = ActionDispatch::Routing::RouteWrapper.new(route)
+          if (path = route_wrapper.path.to_s).starts_with?(base_path)
+            next unless check_path_filter(route, relative_path(path, base_path), path_filter, opts)
+            matching_routes << route_wrapper
+            next
+          end
+        end
+        matching_routes
+      end
+
+      def check_path_filter(route, rel_path, path_filter, opts = {})
+        return true unless path_filter.present?
+        return rel_path == path_filter if path_filter.is_a?(String)
+        return rel_path =~ path_filter if path_filter.is_a?(Regexp)
+        return path_filter.include?(rel_path) if path_filter.is_a?(Array)
+        if path_filter.respond_to?(:call) && path_filter.respond_to?(:parameters)
+          route_opts = opts.merge(route: route, controller: route.defaults[:controller],
+              action: route.defaults[:action])
+          rslt = path_filter.send(*([:call, rel_path, route_opts][0..path_filter.parameters.size]))
+          return rslt ? true : false
+        end
+        false
+      end
+
+      def build_parameter_metadata(endpoint_metadata)
+        parameters = {}
+        parameters = (parameters.is_a?(Array) ? parameters : []) +
+            param_array(endpoint_metadata.delete(:headers), :header) +
+            param_array(endpoint_metadata.delete(:path_params), :path) +
+            param_array(endpoint_metadata.delete(:query_string), :query) +
+            param_array(endpoint_metadata.delete(:form_data), :form_data)
+        if (body_param = endpoint_metadata.delete(:body)).is_a?(Hash)
+          parameters += param_array({ body: body_param }, :body)
+        end
+        return unless parameters.present?
+        endpoint_metadata[:parameters] = OpenApi::Utils.camelize_metadata(parameters, end_depth: 3)
+      end
+
+      private
+
+      def param_array(hash, param_in)
+        return [] if hash.nil?
+        fail "Expected Hash for parameter type '#{param_in}'!" unless hash.is_a?(Hash)
+        hash.map do |key, value|
+          { name: key, in: OpenApi::Utils.camelize_key(param_in) }.merge(
+              value.reject { |k, _v| [:name, :in].include?(k) })
+        end
+      end
+    end
+
+    module Controller
+      module ClassMethods
+        def open_api_path(path, metadata = nil)
+          @open_api_path_metadata ||= {} if metadata.present?
+          OpenApi::Utils.metadata_by_string_or_regexp(@open_api_path_metadata, path, metadata,
+              arg_name: 'path')
+        end
+
+        def open_api_path_param(path_param, param_metadata)
+          regexp = %r{(\A|\/)\:#{path_param}(\Z|\/)|\(\.\:#{path_param}\)}
+          open_api_path regexp, path_params: {
+              path_param.to_s => { type: :integer, required: true }.merge(param_metadata)
+          }
+        end
+
+        def open_api_controller(metadata = nil)
+          return (@open_api_controller_metadata || {}).deep_dup if metadata.blank?
+          fail 'Expected Hash argument for open_api_controller()!' unless metadata.is_a?(Hash)
+          OpenApi::Endpoints.merge_metadata(@open_api_controller_metadata ||= {}, metadata)
+          nil
+        end
+
+        def open_api_action(action, metadata = nil)
+          @open_api_action_metadata ||= {} if metadata.present?
+          OpenApi::Utils.metadata_by_string_or_regexp(@open_api_action_metadata, action, metadata,
+              arg_name: 'action')
+        end
+
+        def open_api_endpoint_metadata(action, path, opts = {})
+          path = OpenApi::Endpoints.relative_path(path, opts[:base_path])
+          controller_class_hierarchy = OpenApi::Utils.controller_class_hierarchy(self)
+          aggr_controller_metadata = {}
+          controller_class_hierarchy.each do |controller_class|
+            OpenApi::Endpoints.merge_metadata(aggr_controller_metadata,
+                controller_class.send(:open_api_controller), opts)
+          end
+          aggr_path_metadata = {}
+          controller_class_hierarchy.each do |controller_class|
+            OpenApi::Endpoints.merge_metadata(aggr_path_metadata,
+                controller_class.send(:open_api_path, path), opts)
+          end
+          aggr_action_metadata = {}
+          controller_class_hierarchy.each do |controller_class|
+            OpenApi::Endpoints.merge_metadata(aggr_action_metadata,
+                controller_class.send(:open_api_action, action), opts)
+          end
+          OpenApi::Endpoints.merge_metadata(aggr_controller_metadata,
+              OpenApi::Endpoints.merge_metadata(aggr_action_metadata, aggr_path_metadata,
+                  opts), opts)
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/open-api/generator.rb

@@ -0,0 +1,153 @@
+# rubocop:disable Rails/Output
+module OpenApi
+  class Generator
+    HIDDEN_ROOT_KEYS = [:output_file_path, :base_paths]
+    class << self
+      def build(opts = {})
+        base_paths = find_base_paths(opts)
+
+        doc = OpenApi.global_metadata.reject { |k, _v| HIDDEN_ROOT_KEYS.include?(k.to_sym) }
+        doc[:info] = OpenApi::Utils.camelize_metadata(doc[:info]) if doc[:info].is_a?(Hash)
+
+        tags, paths, definitions = build_endpoint_content(base_paths, opts)
+        doc[:tags] = OpenApi::Utils.camelize_metadata(tags.values) if tags.present?
+        doc[:paths] = OpenApi::Utils.camelize_metadata(paths, start_depth: 2, end_depth: 4)
+        doc[:definitions] = OpenApi::Utils.camelize_metadata(definitions, start_depth: 2,
+            end_depth: 3)
+
+        doc = OpenApi::Utils.camelize_metadata(doc, end_depth: 2)
+        doc[:swagger] = doc[:swagger].to_s if doc.include?(:swagger)
+
+        doc
+      end
+
+      def write(opts = {})
+        output_file_path = opts[:output_file_path] || OpenApi.global_metadata[:output_file_path]
+        unless output_file_path.respond_to?(:to_s) && output_file_path.to_s.present?
+          fail 'Missing output file path; Must be passed as output_file_path option, or ' \
+              'output_file_path must be configured in the OpenApi initializer ' \
+              '(config/initializers/open_api.rb)'
+        end
+
+        doc = nil
+        File.open(output_file_path.to_s, 'w') do |file|
+          file.write JSON.pretty_generate(doc = build(opts))
+        end
+
+        doc
+      end
+
+      def log_message(level, message, opts = {})
+        unless [:debug, :info, :warn, :error, :fatal].include?(level)
+          fail "Invalid message level: #{level}"
+        end
+        if opts[:stdout]
+          puts "[#{level}] #{message}"
+        else
+          Rails.logger.send(level, message.to_s)
+        end
+      end
+
+      def build_endpoint_content(base_paths, opts = {})
+        paths = {}
+        tags = {}
+        definitions = {}
+        common_base_path = find_common_base_path(base_paths)
+        global_opts = opts.merge(base_path: common_base_path)
+        base_paths.each do |base_path, base_path_opts|
+          opts = global_opts.merge(base_path_opts)
+          OpenApi::Endpoints.find_matching_routes(base_path, opts).each do |route_wrapper|
+            controller_name = (route_wrapper.controller).split('/').map(&:camelize).join('::') +
+                'Controller'
+            controller = controller_name.constantize
+            if controller.nil?
+              log_message(:warn, "Can't resolve controller: #{route_wrapper.controller}", opts)
+              next
+            end
+            next unless controller.respond_to?(:open_api_endpoint_metadata)
+            endpoint_metadata = controller.open_api_endpoint_metadata(route_wrapper.action,
+                route_wrapper.path, opts.merge(base_path: base_path))
+            next if endpoint_metadata[:hidden]
+            path = add_path(route_wrapper, paths, common_base_path, opts)
+            next if path.nil?
+            OpenApi::Endpoints.build_parameter_metadata(endpoint_metadata)
+            endpoint_metadata = OpenApi::Objects.resolve_refs(endpoint_metadata, definitions,
+                controller, opts)
+            endpoint_metadata = OpenApi::Tags.resolve_refs(endpoint_metadata, tags, controller,
+                opts)
+            path[OpenApi::Endpoints.verb_key(route_wrapper)] = endpoint_metadata
+          end
+        end
+        [tags, paths, definitions]
+      end
+
+      def add_path(route_wrapper, paths, common_base_path, opts = {})
+        relative_path = OpenApi::Endpoints.relative_path(route_wrapper.path.to_s, common_base_path)
+        route_wrapper.parts.each do |path_param|
+          relative_path = relative_path
+              .gsub(%r{(\A|\/)\:(#{path_param})(\Z|\/)}, '\1{\2}\3')
+              .gsub(/\(\.\:#{path_param}\)/, ".{#{path_param}}")
+        end
+        path = (paths[relative_path] ||= {})
+        verb_key = OpenApi::Endpoints.verb_key(route_wrapper)
+        if path.include?(verb_key)
+          base_message = "Warning: Multiple OpenApi::Endpoints match #{route_wrapper.verb} " \
+            "#{relative_path} ...  skipping entry for route"
+          if route_wrapper.name.present?
+            log_message(:warn, "#{base_message} '#{route_wrapper.name}'", opts)
+          else
+            log_message(:warn, "#{base_message} #{route_wrapper.verb} #{route_wrapper.path}", opts)
+          end
+          return nil
+        end
+        path
+      end
+
+      def find_base_paths(opts = {})
+        base_paths = opts[:base_paths] || OpenApi.global_metadata[:base_paths]
+        if base_paths.is_a?(Array)
+          base_paths = base_paths.map(&:to_s).reject(&:blank?).uniq
+          base_paths = Hash[(base_paths.map do |base_path|
+            [base_path.starts_with?('/') ? base_path : "/#{base_path}", {}]
+          end)]
+        elsif base_paths.is_a?(Hash)
+          base_paths = Hash[(base_paths.map do |base_path, api_opts|
+            fail "Expected options hash for base path '#{base_path}'" unless api_opts.is_a?(Hash)
+            [base_path.starts_with?('/') ? base_path : "/#{base_path}", api_opts]
+          end)]
+        else
+          fail "Invalid value for 'base_paths': Expected Hash or Array"
+        end
+        if base_paths.blank?
+          fail 'Missing API base paths; Must be passed as base_paths option, or base_paths must ' \
+              'be configured in the OpenApi initializer (config/initializers/open_api.rb)'
+        end
+        base_paths
+      end
+
+      def find_common_base_path(base_paths)
+        return nil if base_paths.blank?
+        split_paths = base_paths.map do |base_path|
+          base_path.split('/').reject(&:blank?)
+        end
+        path_count = split_paths.length
+        first_path = split_paths[0]
+        return "/#{first_path.join('/')}" if path_count == 1
+        common_elems = 0
+        while common_elems < first_path.length
+          path_elem_idx = 0
+          while path_elem_idx < path_count - 1
+            cmp_path = split_paths[path_elem_idx + 1]
+            break if cmp_path.length <= common_elems
+            break if cmp_path[common_elems] != first_path[common_elems]
+            path_elem_idx += 1
+          end
+          break if path_elem_idx < path_count - 1
+          common_elems += 1
+        end
+        return '/' if common_elems == 0
+        "/#{first_path[0..(common_elems - 1)].join('/')}"
+      end
+    end
+  end
+end

data/lib/open-api/objects.rb

@@ -0,0 +1,150 @@
+module OpenApi
+  module Objects
+    class << self
+      METADATA_MERGE = {
+          properties: (lambda do |properties, merge_properties, opts|
+            OpenApi::Utils.verify_and_merge_hash(properties, merge_properties, 'properties',
+                opts.merge(recursive_merge: true))
+          end)
+      }
+
+      def merge_metadata(metadata, merge_metadata, opts = {})
+        OpenApi::Utils.merge_hash(metadata, merge_metadata, opts.merge(merge_by: METADATA_MERGE))
+      end
+
+      def resolve_refs(metadata, definitions, controller, opts = {})
+        resolve_proc = -> (object_name) { controller.open_api_object_metadata(object_name) }
+        if metadata.is_a?(Hash)
+          Hash[(metadata.map do |key, value|
+            value = resolve_refs(value, definitions, controller, opts)
+            if ['schema', 'items', '$ref'].include?(key.to_s) && value.respond_to?(:to_sym) &&
+                !(object = resolve_ref(value.to_sym, resolve_proc)).nil?
+              fail 'Expected Hash for definitions!' unless definitions.is_a?(Hash)
+              object = resolve_refs(object, definitions, controller, opts)
+              add_definition(definitions, value.to_sym, object)
+              next [:'$ref', "#/definitions/#{value}"] if key.to_s == '$ref'
+              next [key.to_sym, { :'$ref' => "#/definitions/#{value}" }]
+            end
+            [key, value]
+          end)]
+        elsif metadata.is_a?(Array)
+          metadata.map do |elem|
+            resolve_refs(elem, definitions, controller, opts)
+          end
+        else
+          metadata
+        end
+      end
+
+      private
+
+      def resolve_ref(key, resolve_proc, opts = {})
+        unless resolve_proc.respond_to?(:call) &&
+            resolve_proc.respond_to?(:parameters)
+          fail 'Expected proc/lambda for resolve_proc!'
+        end
+        proc_param_count = resolve_proc.parameters.size
+        fail 'Expected 1+ parameters (object name) for resolve_proc!' if proc_param_count < 1
+        object = resolve_proc.send(*([:call, key, opts][0..proc_param_count]))
+        return nil if object.nil?
+        fail 'Expected hash result from resolve_proc!' unless object.is_a?(Hash)
+        object
+      end
+
+      def add_definition(definitions, key, object)
+        return if object.nil?
+        json = object.to_json
+        retry_index = 0
+        loop do
+          if definitions.include?(key)
+            break if definitions[key].to_json == json
+            retry_index += 1
+            key = "#{key}#{retry_index}".to_sym
+          else
+            definitions[key] = object
+            break
+          end
+        end
+      end
+    end
+
+    module Controller
+      module ClassMethods
+        def open_api_objects(metadata = nil)
+          return (@open_api_objects_metadata || {}).deep_dup if metadata.blank?
+          fail 'Expected Hash argument for open_api_objects()!' unless metadata.is_a?(Hash)
+          metadata.each do |object_key, object_metadata|
+            open_api_object(object_key, object_metadata)
+          end
+          nil
+        end
+
+        def open_api_object(object_key, metadata = nil)
+          fail 'Valid object argument required!' unless object_key.respond_to?(:to_sym)
+          return (@open_api_objects_metadata || {})[object_key.to_sym].deep_dup if metadata.blank?
+          fail 'Expected Hash argument for open_api_object()!' unless metadata.is_a?(Hash)
+          metadata = expand_nested_object_metadata(metadata)
+          object_metadata = ((@open_api_objects_metadata ||= {})[object_key.to_sym] ||= {})
+          OpenApi::Objects.merge_metadata(object_metadata, metadata)
+          nil
+        end
+
+        def expand_nested_object_metadata(metadata)
+          unless metadata[:type].respond_to?(:to_sym) && metadata[:type].to_sym == :object
+            metadata = { type: :object, properties: metadata }
+          end
+          required_attrs = (metadata[:required] || []).map(&:to_sym)
+          if (properties = metadata[:properties]).is_a?(Hash) && properties.present?
+            metadata = metadata.dup
+            properties = Hash[(properties.map do |name, property|
+              property = expand_nested_object_property(name, property, required_attrs)
+              [name, property]
+            end)]
+            metadata[:properties] = properties
+          end
+          metadata[:required] = required_attrs.uniq if required_attrs.present?
+          metadata
+        end
+
+        def expand_nested_object_property(name, property, required_attrs)
+          if property.is_a?(Hash)
+            required = property[:required]
+            if required.nil?
+              required_attrs << name.to_sym # Presume required if required option not spec'd
+            elsif [TrueClass, FalseClass].include?(required.class)
+              required_attrs << name.to_sym if property.delete(:required)
+            end
+            unless property.blank? || property[:type].respond_to?(:to_sym)
+              property = expand_nested_object_metadata(property)
+            end
+          else
+            api_type, api_format = OpenApi::Utils.open_api_type_and_format(property)
+            if api_type.nil?
+              property = { type: :object, '$ref' => property }
+            elsif api_format.present?
+              property = { type: api_type, format: api_format }
+            else
+              property = { type: api_type }
+            end
+            required_attrs << name.to_sym # Presume required if required option not spec'd
+          end
+          property
+        end
+
+        def open_api_object_metadata(object_key, opts = {})
+          controller_class_hierarchy = OpenApi::Utils.controller_class_hierarchy(self)
+          aggr_object_metadata = {}
+          controller_class_hierarchy.each do |controller_class|
+            OpenApi::Objects.merge_metadata(aggr_object_metadata,
+                controller_class.send(:open_api_object, object_key), opts)
+          end
+          aggr_object_metadata
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/open-api/tags.rb

@@ -0,0 +1,149 @@
+module OpenApi
+  class Tags
+    class << self
+      def merge_metadata(metadata, merge_metadata, opts = {})
+        OpenApi::Utils.merge_hash(metadata, merge_metadata, opts.merge(recursive_merge: true))
+      end
+
+      def resolve_refs(metadata, tags, controller, opts = {})
+        opts = opts.symbolize_keys
+        opts[:define_proc] ||=
+            -> (tag_name, tag_metadata) { controller.open_api_tag(tag_name, tag_metadata) }
+        opts[:resolve_proc] ||=
+            -> (tag_name) { controller.open_api_tag_metadata(tag_name) }
+        if metadata.is_a?(Hash)
+          resolve_hash_refs(metadata, tags, controller, opts)
+        elsif metadata.is_a?(Array)
+          metadata.map do |elem|
+            resolve_refs(elem, tags, controller, opts)
+          end
+        else
+          metadata
+        end
+      end
+
+      private
+
+      def resolve_hash_refs(hash, tags, controller, opts)
+        Hash[(hash.map do |key, value|
+          next [key, value] unless %w(tag tags).include?(key.to_s)
+          if key.to_s == 'tag'
+            values = [value]
+          else
+            next [key, value] unless value.is_a?(Array)
+            values = value
+          end
+          values = resolve_tag_values(values, tags, controller, opts)
+          next values.nil? ? [key, values] : [:tags, values]
+        end)]
+      end
+
+      def resolve_tag_values(values, tags, controller, opts = {})
+        define_proc = opts[:define_proc] ||
+            -> (tag_name, metadata) { controller.open_api_tag(tag_name, metadata) }
+        resolve_proc = opts[:resolve_proc] ||
+            -> (tag_name) { controller.open_api_tag_metadata(tag_name) }
+        values = (values.map do |value|
+          if value.is_a?(Hash)
+            next nil unless value[:name].respond_to?(:to_sym)
+            name = value[:name].to_s
+            value = value.merge(name: name)
+            metadata = define_ref(name, value, define_proc, opts)
+            add_tag(tags, name, metadata)
+            name
+          else
+            value.respond_to?(:to_sym) ? value.to_s : nil
+          end
+        end).compact
+        return nil if values.empty?
+        values = (values.map do |tag|
+          next nil unless tag.respond_to?(:to_sym)
+          name = tag.to_s
+          metadata = resolve_ref(name, resolve_proc, opts)
+          fail 'Expected Hash for metadata!' unless metadata.is_a?(Hash)
+          add_tag(tags, name, metadata)
+          name
+        end).compact
+        values
+      end
+
+      def resolve_ref(key, resolve_proc, opts = {})
+        unless resolve_proc.respond_to?(:call) &&
+            resolve_proc.respond_to?(:parameters)
+          fail 'Expected proc/lambda for resolve_proc!'
+        end
+        proc_param_count = resolve_proc.parameters.size
+        fail 'Expected 1+ parameters (tag) for resolve_proc!' if proc_param_count < 1
+        tag = resolve_proc.send(*([:call, key, opts][0..proc_param_count]))
+        return nil if tag.nil?
+        fail 'Expected hash result from resolve_proc!' unless tag.is_a?(Hash)
+        tag
+      end
+
+      def define_ref(key, metadata, define_proc, opts = {})
+        unless define_proc.respond_to?(:call) &&
+            define_proc.respond_to?(:parameters)
+          fail 'Expected proc/lambda for define_proc!'
+        end
+        proc_param_count = define_proc.parameters.size
+        fail 'Expected 2+ parameters (tag, metadata) for define_proc!' if proc_param_count < 1
+        tag = define_proc.send(*([:call, key, metadata, opts][0..proc_param_count]))
+        return nil if tag.nil?
+        fail 'Expected hash result from define_proc!' unless tag.is_a?(Hash)
+        tag
+      end
+
+      def add_tag(tags, tag, metadata)
+        return if metadata.nil?
+        json = metadata.to_json
+        retry_index = 0
+        loop do
+          if tags.include?(tag)
+            break if tags[tag].to_json == json
+            retry_index += 1
+            tag = "#{tag} (#{retry_index})".to_s
+          else
+            tags[tag] = metadata
+            break
+          end
+        end
+      end
+    end
+
+    module Controller
+      module ClassMethods
+        def open_api_tags(metadata = nil)
+          return (@open_api_tags_metadata || {}).deep_dup if metadata.blank?
+          fail 'Expected Hash argument for open_api_tags()!' unless metadata.is_a?(Hash)
+          metadata.each { |tag, tag_metadata| open_api_tag(tag, tag_metadata) }
+          (@open_api_tags_metadata || {})
+          nil
+        end
+
+        def open_api_tag(tag, metadata = nil)
+          fail 'Valid tag argument required!' unless tag.respond_to?(:to_s)
+          return (@open_api_tags_metadata || {})[tag.to_s].deep_dup if metadata.blank?
+          fail 'Expected Hash argument for open_api_tag()!' unless metadata.is_a?(Hash)
+          metadata = { name: tag.to_s }.merge(metadata) unless metadata.include?(:name)
+          tag_metadata = ((@open_api_tags_metadata ||= {})[tag.to_s] ||= {})
+          OpenApi::Tags.merge_metadata(tag_metadata, metadata)
+          nil
+        end
+
+        def open_api_tag_metadata(tag, opts = {})
+          controller_class_hierarchy = OpenApi::Utils.controller_class_hierarchy(self)
+          aggr_metadata = {}
+          controller_class_hierarchy.each do |controller_class|
+            OpenApi::Tags.merge_metadata(aggr_metadata,
+                controller_class.send(:open_api_tag, tag), opts)
+          end
+          aggr_metadata
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/open-api/utils.rb

@@ -0,0 +1,131 @@
+module OpenApi
+  class Utils
+    class << self
+      def controller_class_hierarchy(controller_class)
+        controller_class_hierarchy = [controller_class]
+        loop do
+          controller_class = controller_class.superclass
+          break if controller_class.nil? || !controller_class.respond_to?(:open_api_controller)
+          controller_class_hierarchy << controller_class
+        end
+        controller_class_hierarchy
+      end
+
+      def verify_and_merge_hash(hash, merge_hash, hash_desc, opts = {})
+        return (hash || {}) if merge_hash.nil?
+        fail "Expected #{hash_desc} in the form of a Hash!" unless merge_hash.is_a?(Hash)
+        merge_hash(hash, merge_hash, opts)
+      end
+
+      def merge_hash(hash, merge_hash, opts = {})
+        hash ||= {}
+        return hash if merge_hash.nil?
+        fail 'Expected Hash!' unless merge_hash.is_a?(Hash)
+        merge_hash.each do |key, value|
+          if hash.include?(key)
+            merge_hash_entry(hash, key, value, opts)
+          elsif !value.nil?
+            hash[key] = value
+          end
+        end
+        hash
+      end
+
+      def camelize_metadata(metadata, opts = {})
+        if (start_depth = opts[:start_depth].to_i) > 0
+          start_depth -= 1
+          if start_depth > 0
+            opts = opts.merge(start_depth: start_depth)
+          else
+            (opts = opts.dup).delete(:start_depth)
+          end
+        end
+        if (end_depth = opts[:end_depth]).present?
+          end_depth -= 1
+          return metadata if end_depth <= 0
+          opts = opts.merge(end_depth: end_depth)
+        end
+        if metadata.is_a?(Hash)
+          Hash[(metadata.map do |k, v|
+            [start_depth > 0 ? k : camelize_key(k), camelize_metadata(v, opts)]
+          end)]
+        elsif metadata.is_a?(Array)
+          metadata.map { |v| camelize_metadata(v, opts) }
+        else
+          metadata
+        end
+      end
+
+      def camelize_key(key)
+        key.to_s.camelize(:lower).to_sym
+      end
+
+      def metadata_by_string_or_regexp(metadata_map, string_or_regexp, metadata, opts = {})
+        arg_ref = "#{opts[:arg_name]} argument".strip
+        if metadata.blank?
+          fail "Valid #{arg_ref} required!" unless string_or_regexp.respond_to?(:to_sym)
+          response_metadata = {}
+          (metadata_map || {}).each do |key, item_metadata|
+            if key.is_a?(Regexp)
+              next unless string_or_regexp =~ key
+            else
+              next unless string_or_regexp.casecmp(key) == 0
+            end
+            OpenApi::Endpoints.merge_metadata(response_metadata, item_metadata.deep_dup)
+          end
+          return response_metadata
+        end
+        unless string_or_regexp.respond_to?(:to_sym) || string_or_regexp.is_a?(Regexp)
+          fail "Valid #{arg_ref} required!"
+        end
+        fail 'Expected Hash metadata_map argument!' unless metadata_map.is_a?(Hash)
+        fail 'Expected Hash metadata argument!' unless metadata.is_a?(Hash)
+        string_or_regexp = string_or_regexp.to_s unless string_or_regexp.is_a?(Regexp)
+        existing_metadata = (metadata_map[string_or_regexp] ||= {})
+        OpenApi::Endpoints.merge_metadata(existing_metadata, metadata)
+        nil
+      end
+
+      def open_api_type_and_format(type_name)
+        case type_name.to_s.downcase.to_sym
+        when :integer then   [:integer, :int32]
+        when :long then      [:integer, :int]
+        when :float then     [:number,  :float]
+        when :double then    [:number,  :double]
+        when :string then    [:string,  nil]
+        when :byte then      [:string,  :byte]
+        when :binary then    [:string,  :binary]
+        when :boolean then   [:boolean, nil]
+        when :date then      [:string,  :date]
+        when :datetime then  [:string,  :'date-time']
+        when :password then  [:string,  :password]
+        else                 [nil, nil]
+        end
+      end
+
+      private
+
+      def merge_hash_entry(hash, key, value, opts)
+        merge_by_hash = opts[:merge_by] || {}
+        if (merge_by = merge_by_hash[key]).present?
+          if merge_by.respond_to?(:call) && merge_by.respond_to?(:parameters)
+            if (param_count = merge_by.parameters.size) < 2
+              fail "Expected 2+ parameters (existing/merged values) for '#{key}' merge_by proc!"
+            end
+            merge_by.send(*([:call, hash[key], value, opts][0..param_count]))
+          end
+        elsif hash[key].is_a?(Hash) && value.is_a?(Hash)
+          if opts[:recursive_merge]
+            merge_hash(hash[key], value, opts)
+          else
+            hash[key].merge!(value)
+          end
+        elsif value.nil?
+          hash.delete(key)
+        else
+          hash[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/open-api.rb

@@ -0,0 +1,35 @@
+require 'open-api/controller.rb'
+require 'open-api/endpoints.rb'
+require 'open-api/generator.rb'
+require 'open-api/objects.rb'
+require 'open-api/tags.rb'
+require 'open-api/utils.rb'
+
+module OpenApi
+  class << self
+    def configure(metadata = nil, &block)
+      return unless metadata.is_a?(Hash) || block_given?
+      global_metadata = @open_api_global_metadata || default_global_metadata
+      if metadata.is_a?(Hash)
+        global_metadata = OpenApi::Utils.merge_hash(global_metadata, metadata)
+      end
+      if block_given?
+        config = OpenStruct.new(global_metadata)
+        block.call(config)
+        global_metadata = OpenApi::Utils.merge_hash(global_metadata, config.to_h.symbolize_keys)
+      end
+      @open_api_global_metadata = global_metadata
+    end
+
+    def global_metadata
+      @open_api_global_metadata || default_global_metadata
+    end
+
+    def default_global_metadata
+      {
+          swagger: 2.0,
+          schemes: [:http]
+      }
+    end
+  end
+end

data/open-api.gemspec

@@ -0,0 +1,24 @@
+lib = File.expand_path("../lib", __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+Gem::Specification.new do |s|
+  s.name = 'open-api'
+  s.version = '0.8.2'
+  s.summary = 'Inline Openi API documentation for Ruby on Rails'
+  s.description = 'Provides the ability to specify Open API documentation inline within the ' \
+      'source code of your Ruby on Rails project, utilizing a rake task to generate / maintain ' \
+      'that documentation as required.'
+  s.licenses = ['Apache 2']
+  s.authors = ['Matthew Mead']
+  s.email = 'm.mead@precisionhawk.com'
+
+  s.files = Dir.glob("{lib,spec,config}/**/*")
+  s.files += %w(open-api.gemspec README.md)
+
+  s.require_path = "lib"
+
+  s.add_dependency "rails", ">= 4.0"
+
+  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "factory_girl"
+end

metadata

@@ -1,15 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: open-api
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Matthew Mead
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-27 00:00:00.000000000 Z
-dependencies: []
+date: 2016-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  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: factory_girl
+  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: Provides the ability to specify Open API documentation inline within
   the source code of your Ruby on Rails project, utilizing a rake task to generate
   / maintain that documentation as required.
@@ -17,7 +59,16 @@ email: m.mead@precisionhawk.com
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- README.md
+- lib/open-api.rb
+- lib/open-api/controller.rb
+- lib/open-api/endpoints.rb
+- lib/open-api/generator.rb
+- lib/open-api/objects.rb
+- lib/open-api/tags.rb
+- lib/open-api/utils.rb
+- open-api.gemspec
 homepage: 
 licenses:
 - Apache 2