swagger-blocks 1.4.0 → 2.0.0

data/lib/swagger/blocks/class_methods.rb

@@ -0,0 +1,65 @@
+module Swagger
+  module Blocks
+    module ClassMethods
+      private
+
+      # v2.0: Defines a Swagger Object
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#swagger-object
+      def swagger_root(inline_keys = nil, &block)
+        @swagger_root_node ||= Swagger::Blocks::Nodes::RootNode.call(inline_keys: inline_keys, &block)
+      end
+
+      # v2.0: Defines a Swagger Path Item object
+      # https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#path-item-object
+      def swagger_path(path, &block)
+        path = path.to_sym
+
+        # TODO enforce that path name begins with a '/'
+        #   (or x- , but need to research Vendor Extensions first)
+
+        @swagger_path_node_map ||= {}
+
+        path_node = @swagger_path_node_map[path]
+        if path_node
+          # Merge this path declaration into the previous one
+          path_node.instance_eval(&block)
+        else
+          # First time we've seen this path
+          @swagger_path_node_map[path] = Swagger::Blocks::Nodes::PathNode.call(version: '2.0', &block)
+        end
+      end
+
+      # v2.0: Defines a Swagger Definition Schema,
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject and
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema-object
+      def swagger_schema(name, inline_keys = nil, &block)
+        @swagger_schema_node_map ||= {}
+
+        schema_node = @swagger_schema_node_map[name]
+        if schema_node
+          # Merge this schema_node declaration into the previous one
+          schema_node.instance_eval(&block)
+        else
+          # First time we've seen this schema_node
+          @swagger_schema_node_map[name] = Swagger::Blocks::Nodes::SchemaNode.call(version: '2.0', inline_keys: inline_keys, &block)
+        end
+      end
+
+      def _swagger_nodes
+        # Avoid initialization warnings.
+        @swagger_root_node ||= nil
+        @swagger_path_node_map ||= {}
+        @swagger_schema_node_map ||= nil
+        @swagger_api_root_node_map ||= {}
+        @swagger_models_node ||= nil
+
+        data = {root_node: @swagger_root_node}
+        data[:path_node_map] = @swagger_path_node_map
+        data[:schema_node_map] = @swagger_schema_node_map
+        data[:api_node_map] = @swagger_api_root_node_map
+        data[:models_node] = @swagger_models_node
+        data
+      end
+    end
+  end
+end

data/lib/swagger/blocks/errors.rb

@@ -0,0 +1,8 @@
+module Swagger
+  module Blocks
+    class Error < StandardError; end
+    class DeclarationError < Error; end
+    class NotFoundError < Error; end
+    class NotSupportedError < Error; end
+  end
+end

data/lib/swagger/blocks/internal_helpers.rb

@@ -0,0 +1,52 @@
+module Swagger
+  module Blocks
+    module InternalHelpers
+      # Return [root_node, api_node_map] from all of the given swaggered_classes.
+      def self.parse_swaggered_classes(swaggered_classes)
+        root_nodes = []
+
+        api_node_map = {}
+        models_nodes = []
+
+        path_node_map = {}
+        schema_node_map = {}
+        swaggered_classes.each do |swaggered_class|
+          next unless swaggered_class.respond_to?(:_swagger_nodes, true)
+          swagger_nodes = swaggered_class.send(:_swagger_nodes)
+          root_node = swagger_nodes[:root_node]
+          root_nodes << root_node if root_node
+
+          # 2.0
+          if swagger_nodes[:path_node_map]
+            path_node_map.merge!(swagger_nodes[:path_node_map])
+          end
+          if swagger_nodes[:schema_node_map]
+            schema_node_map.merge!(swagger_nodes[:schema_node_map])
+          end
+        end
+        data = {root_node: self.limit_root_node(root_nodes)}
+        if data[:root_node].is_swagger_2_0?
+          data[:path_nodes] = path_node_map
+          data[:schema_nodes] = schema_node_map
+        else
+          data[:api_node_map] = api_node_map
+          data[:models_nodes] = models_nodes
+        end
+        data
+      end
+
+      # Make sure there is exactly one root_node and return it.
+      # TODO should this merge the contents of the root nodes instead?
+      def self.limit_root_node(root_nodes)
+        if root_nodes.length == 0
+          raise Swagger::Blocks::DeclarationError.new(
+            'swagger_root must be declared')
+        elsif root_nodes.length > 1
+          raise Swagger::Blocks::DeclarationError.new(
+            'Only one swagger_root declaration is allowed.')
+        end
+        root_nodes.first
+      end
+    end
+  end
+end

data/lib/swagger/blocks/node.rb

@@ -0,0 +1,64 @@
+module Swagger
+  module Blocks
+    # Base node for representing every object in the Swagger DSL.
+    class Node
+      attr_accessor :name
+      attr_writer :version
+
+      def self.call(options = {}, &block)
+        # Create a new instance and evaluate the block into it.
+        instance = new
+        instance.name = options[:name] if options[:name]
+        instance.version = options[:version]
+        instance.keys options[:inline_keys]
+        instance.instance_eval(&block) if block
+        instance
+      end
+
+      def as_json
+        result = {}
+
+        self.data.each do |key, value|
+          if value.is_a?(Node)
+            result[key] = value.as_json
+          elsif value.is_a?(Array)
+            result[key] = []
+            value.each { |v| result[key] << (v.respond_to?(:as_json) ? v.as_json : v) }
+          elsif is_swagger_2_0? && value.is_a?(Hash)
+            result[key] = {}
+            value.each_pair {|k, v| result[key][k] = (v.respond_to?(:as_json) ? v.as_json : v) }
+          elsif is_swagger_2_0? && key.to_s.eql?('$ref') && (value.to_s !~ %r{^#/|https?://})
+            result[key] = "#/definitions/#{value}"
+          else
+            result[key] = value
+          end
+        end
+        return result if !name
+        # If 'name' is given to this node, wrap the data with a root element with the given name.
+        {name => result}
+      end
+
+      def data
+        @data ||= {}
+      end
+
+      def keys(data)
+        self.data.merge!(data) if data
+      end
+
+      def key(key, value)
+        self.data[key] = value
+      end
+
+      def version
+        return @version if instance_variable_defined?('@version') && @version
+        return '2.0' if data.has_key?(:swagger) && data[:swagger] == '2.0'
+        raise DeclarationError, "You must specify swagger '2.0'"
+      end
+
+      def is_swagger_2_0?
+        version == '2.0'
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/all_of_node.rb

@@ -0,0 +1,42 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class AllOfNode < Node
+        def as_json
+          result = []
+
+          self.data.each do |value|
+            if value.is_a?(Node)
+              result << value.as_json
+            elsif value.is_a?(Array)
+              r = []
+              value.each { |v| r << (v.respond_to?(:as_json) ? v.as_json : v) }
+              result << r
+            elsif is_swagger_2_0? && value.is_a?(Hash)
+              r = {}
+              value.each_pair {|k, v| r[k] = (v.respond_to?(:as_json) ? v.as_json : v) }
+              result << r
+            else
+              result = value
+            end
+          end
+          return result if !name
+          # If 'name' is given to this node, wrap the data with a root element with the given name.
+          {name => result}
+        end
+
+        def data
+          @data ||= []
+        end
+
+        def key(key, value)
+          raise NotSupportedError
+        end
+
+        def schema(inline_keys = nil, &block)
+          data << Swagger::Blocks::Nodes::SchemaNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/contact_node.rb

@@ -0,0 +1,9 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#contact-object
+      class ContactNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/example_node.rb

@@ -0,0 +1,9 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0:
+      class ExampleNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/external_docs_node.rb

@@ -0,0 +1,9 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#externalDocumentationObject
+      class ExternalDocsNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/header_node.rb

@@ -0,0 +1,12 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#headerObject
+      class HeaderNode < Node
+        def items(inline_keys = nil, &block)
+          self.data[:items] = Swagger::Blocks::Nodes::ItemsNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/info_node.rb

@@ -0,0 +1,16 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject
+      class InfoNode < Node
+        def contact(inline_keys = nil, &block)
+          self.data[:contact] = Swagger::Blocks::Nodes::ContactNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def license(inline_keys = nil, &block)
+          self.data[:license] = Swagger::Blocks::Nodes::LicenseNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/items_node.rb

@@ -0,0 +1,14 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0:
+      class ItemsNode < Node
+        def property(name, inline_keys = nil, &block)
+          self.data[:properties] ||= Swagger::Blocks::Nodes::PropertiesNode.new
+          self.data[:properties].version = version
+          self.data[:properties].property(name, inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/license_node.rb

@@ -0,0 +1,9 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#license-object
+      class LicenseNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/operation_node.rb

@@ -0,0 +1,30 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object
+      class OperationNode < Node
+        def parameter(inline_keys = nil, &block)
+          inline_keys = {'$ref' => "#/parameters/#{inline_keys}"} if inline_keys.is_a?(Symbol)
+
+          self.data[:parameters] ||= []
+          self.data[:parameters] << Swagger::Blocks::Nodes::ParameterNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def response(resp, inline_keys = nil, &block)
+          # TODO validate 'resp' is as per spec
+          self.data[:responses] ||= {}
+          self.data[:responses][resp] = Swagger::Blocks::Nodes::ResponseNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def externalDocs(inline_keys = nil, &block)
+          self.data[:externalDocs] = Swagger::Blocks::Nodes::ExternalDocsNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def security(inline_keys = nil, &block)
+          self.data[:security] ||= []
+          self.data[:security] << Swagger::Blocks::Nodes::SecurityRequirementNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/parameter_node.rb

@@ -0,0 +1,16 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object
+      class ParameterNode < Node
+        def schema(inline_keys = nil, &block)
+          self.data[:schema] = Swagger::Blocks::Nodes::SchemaNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def items(inline_keys = nil, &block)
+          self.data[:items] = Swagger::Blocks::Nodes::ItemsNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/path_node.rb

@@ -0,0 +1,24 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#path-item-object
+      class PathNode < Node
+        OPERATION_TYPES = [:get, :put, :post, :delete, :options, :head, :patch].freeze
+
+        # TODO support ^x- Vendor Extensions
+        def operation(op, inline_keys = nil, &block)
+          op = op.to_sym
+          raise ArgumentError.new("#{name} not in #{OPERATION_TYPES}") if !OPERATION_TYPES.include?(op)
+          self.data[op] = Swagger::Blocks::Nodes::OperationNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def parameter(inline_keys = nil, &block)
+          inline_keys = {'$ref' => "#/parameters/#{inline_keys}"} if inline_keys.is_a?(Symbol)
+
+          self.data[:parameters] ||= []
+          self.data[:parameters] << Swagger::Blocks::Nodes::ParameterNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/properties_node.rb

@@ -0,0 +1,11 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class PropertiesNode < Node
+        def property(name, inline_keys = nil, &block)
+          self.data[name] = Swagger::Blocks::Nodes::PropertyNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/property_node.rb

@@ -0,0 +1,17 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class PropertyNode < Node
+        def items(inline_keys = nil, &block)
+          self.data[:items] = Swagger::Blocks::Nodes::ItemsNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def property(name, inline_keys = nil, &block)
+          self.data[:properties] ||= Swagger::Blocks::Nodes::PropertiesNode.new
+          self.data[:properties].version = version
+          self.data[:properties].property(name, inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/response_node.rb

@@ -0,0 +1,24 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responseObject
+      class ResponseNode < Node
+        def schema(inline_keys = nil, &block)
+          self.data[:schema] = Swagger::Blocks::Nodes::SchemaNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def header(head, inline_keys = nil, &block)
+          # TODO validate 'head' is as per spec
+          self.data[:headers] ||= {}
+          self.data[:headers][head] = Swagger::Blocks::Nodes::HeaderNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def example(exam, inline_keys = nil, &block)
+          # TODO validate 'exam' is as per spec
+          self.data[:examples] ||= {}
+          self.data[:examples][exam] = Swagger::Blocks::Nodes::ExampleNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end