swagger-blocks 1.0.1 → 1.1

data/lib/swagger/blocks.rb

@@ -3,10 +3,12 @@ require 'swagger/blocks/version'
 
 module Swagger
   module Blocks
+
     # Some custom error classes.
     class Error < Exception; end
     class DeclarationError < Error; end
     class NotFoundError < Error; end
+    class NotSupportedError < Error; end
 
     # Inject the swagger_root, swagger_api_root, and swagger_model class methods.
     def self.included(base)
@@ -15,11 +17,26 @@ module Swagger
 
     def self.build_root_json(swaggered_classes)
       data = Swagger::Blocks::InternalHelpers.parse_swaggered_classes(swaggered_classes)
+
+      if data[:root_node].is_swagger_2_0?
+        data[:root_node].key(:paths, data[:path_nodes]) # Required, so no empty check.
+        if data[:schema_nodes] && !data[:schema_nodes].empty?
+          data[:root_node].key(:definitions, data[:schema_nodes])
+        end
+      end
+
       data[:root_node].as_json
     end
 
     def self.build_api_json(resource_name, swaggered_classes)
       data = Swagger::Blocks::InternalHelpers.parse_swaggered_classes(swaggered_classes)
+      if !data[:root_node].is_swagger_1_2?
+        raise NotSupportedError.new(
+          'build_api_json only supports Swagger 1.2, you do not need to call this method ' +
+          'for Swagger >= 2.0 definitions.'
+        )
+      end
+
       api_node = data[:api_node_map][resource_name.to_sym]
       raise Swagger::Blocks::NotFoundError.new(
         "Not found: swagger_api_root named #{resource_name}") if !api_node
@@ -36,27 +53,48 @@ module Swagger
       # 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 if !swaggered_class.respond_to?(:_swagger_nodes, true)
+          next unless swaggered_class.respond_to?(:_swagger_nodes, true)
           swagger_nodes = swaggered_class.send(:_swagger_nodes)
-          root_node = swagger_nodes[:resource_listing_node]
+          root_node = swagger_nodes[:root_node]
           root_nodes << root_node if root_node
-          api_node_map.merge!(swagger_nodes[:api_node_map])
-          models_nodes << swagger_nodes[:models_node] if swagger_nodes[:models_node]
-        end
-        root_node = self.get_resource_listing(root_nodes)
 
-        {
-          root_node: root_node,
-          api_node_map: api_node_map,
-          models_nodes: models_nodes,
-        }
+          # 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
+
+          # 1.2
+          if swagger_nodes[:api_node_map]
+            api_node_map.merge!(swagger_nodes[:api_node_map])
+          end
+          if swagger_nodes[:models_node]
+            models_nodes << swagger_nodes[:models_node]
+          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.
-      def self.get_resource_listing(root_nodes)
+      # 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')
@@ -71,17 +109,19 @@ module Swagger
     module ClassMethods
       private
 
-      # Defines a Swagger Resource Listing.
-      # http://goo.gl/PvwUXj#51-resource-listing
+      # v1.2: Defines a Swagger Resource Listing.
+      # v1.2: http://goo.gl/PvwUXj#51-resource-listing
+      # 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(&block)
-        @swagger_root_node ||= Swagger::Blocks::ResourceListingNode.call(&block)
+        @swagger_root_node ||= Swagger::Blocks::RootNode.call(&block)
       end
 
-      # Defines a Swagger API Declaration.
-      # http://goo.gl/PvwUXj#52-api-declaration
-      #
-      # @param resource_name [Symbol] An identifier for this API. All swagger_api_root declarations
-      #   with the same resource_name will be merged into a single API root node.
+      # v1.2: Defines a Swagger API Declaration.
+      # v1.2: http://goo.gl/PvwUXj#52-api-declaration
+      # v1.2:
+      # v1.2: @param resource_name [Symbol] An identifier for this API. All swagger_api_root declarations
+      # v1.2:   with the same resource_name will be  into a single API root node.
       def swagger_api_root(resource_name, &block)
         resource_name = resource_name.to_sym
 
@@ -96,30 +136,73 @@ module Swagger
           api_node.instance_eval(&block)
         else
           # First time we've seen this `swagger_api_root :resource_name`.
-          api_node = Swagger::Blocks::ApiDeclarationNode.call(&block)
+          api_node = Swagger::Blocks::ApiDeclarationNode.call(version: '1.2', &block)
         end
 
         # Add it into the resource_name to node map (may harmlessly overwrite the same object).
         @swagger_api_root_node_map[resource_name] = api_node
       end
 
-      # Defines a Swagger Model.
-      # http://goo.gl/PvwUXj#526-models-object
+      # 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::PathNode.call(version: '2.0', &block)
+        end
+      end
+
+      # v1.2: Defines a Swagger Model.
+      # v1.2: http://goo.gl/PvwUXj#526-models-object
       def swagger_model(name, &block)
         @swagger_models_node ||= Swagger::Blocks::ModelsNode.new
+        @swagger_models_node.version = '1.2'
         @swagger_models_node.model(name, &block)
       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, &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::SchemaNode.call(version: '2.0', &block)
+        end
+      end
+
       def _swagger_nodes
-        @swagger_root_node ||= nil  # Avoid initialization warnings.
+        # 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
-        {
-          resource_listing_node: @swagger_root_node,
-          api_node_map: @swagger_api_root_node_map,
-          models_node: @swagger_models_node,
-        }
+
+        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
 
     # -----
@@ -127,29 +210,37 @@ module Swagger
     # 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.instance_eval(&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{^#/definitions/})
+            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.
+        # If 'name' is given to this node, wrap the data with a root element with the given name.
         {name => result}
       end
 
@@ -160,118 +251,191 @@ module Swagger
       def key(key, value)
         self.data[key] = value
       end
-    end
 
-    # -----
-    # Nodes for the Resource Listing.
-    # -----
+      def version
+        return @version if instance_variable_defined?('@version') && @version
+        if data.has_key?(:swagger) && data[:swagger] == '2.0'
+          '2.0'
+        elsif data.has_key?(:swaggerVersion) && data[:swaggerVersion] == '1.2'
+          '1.2'
+        else
+          raise DeclarationError.new("You must specify swaggerVersion '1.2' or swagger '2.0'")
+        end
+      end
 
-    # http://goo.gl/PvwUXj#51-resource-listing
-    class ResourceListingNode < Node
+      def is_swagger_1_2?
+        version == '1.2'
+      end
+
+      def is_swagger_2_0?
+        version == '2.0'
+      end
+    end
+
+    class RootNode < Node
       def initialize(*args)
         # An internal list of the user-defined names that uniquely identify each API tree.
+        # Only used in Swagger 1.2, but when initializing a root node we haven't seen the
+        # swaggerVersion/swagger key yet
         @api_paths = []
         super
       end
 
       def has_api_path?(api_path)
+        raise NotSupportedError unless is_swagger_1_2?
+
         api_paths = self.data[:apis].map { |x| x.data[:path] }
         api_paths.include?(api_path)
       end
 
-      def info(&block)
-        self.data[:info] = InfoNode.call(&block)
-      end
-
       def authorization(name, &block)
+        raise NotSupportedError unless is_swagger_1_2?
+
         self.data[:authorizations] ||= Swagger::Blocks::ResourceListingAuthorizationsNode.new
+        self.data[:authorizations].version = version
         self.data[:authorizations].authorization(name, &block)
       end
 
+      def info(&block)
+        self.data[:info] = Swagger::Blocks::InfoNode.call(version: version, &block)
+      end
+
       def api(&block)
+        raise NotSupportedError unless is_swagger_1_2?
+
         self.data[:apis] ||= []
-        self.data[:apis] << Swagger::Blocks::ResourceNode.call(&block)
+        self.data[:apis] << Swagger::Blocks::ResourceNode.call(version: version, &block)
+      end
+
+      def parameter(param, &block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        # TODO validate 'param' is as per spec
+        self.data[:parameters] ||= {}
+        self.data[:parameters][param] = Swagger::Blocks::ParameterNode.call(version: version, &block)
+      end
+
+      def response(resp, &block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        # TODO validate 'resp' is as per spec
+        self.data[:responses] ||= {}
+        self.data[:responses][resp] = Swagger::Blocks::ResponseNode.call(version: version, &block)
+      end
+
+      def security_definition(name, &block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:securityDefinitions] ||= {}
+        self.data[:securityDefinitions][name] = Swagger::Blocks::SecuritySchemeNode.call(version: version, &block)
+      end
+
+      def security(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:security] ||= []
+        self.data[:security] << Swagger::Blocks::SecurityRequirementNode.call(version: version, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#512-resource-object
+    # v1.2: http://goo.gl/PvwUXj#512-resource-object
     class ResourceNode < Node; end
 
-    # NOTE: in the spec this is different than API Declaration authorizations.
-    # http://goo.gl/PvwUXj#514-authorizations-object
+    # v1.2: NOTE: in the spec this is different than API Declaration authorizations.
+    # v1.2: http://goo.gl/PvwUXj#514-authorizations-object
     class ResourceListingAuthorizationsNode < Node
       def authorization(name, &block)
-        self.data[name] = Swagger::Blocks::ResourceListingAuthorizationNode.call(&block)
+        self.data[name] = Swagger::Blocks::ResourceListingAuthorizationNode.call(version: version, &block)
       end
     end
 
-    # NOTE: in the spec this is different than API Declaration authorization.
-    # http://goo.gl/PvwUXj#515-authorization-object
+    # v1.2: NOTE: in the spec this is different than API Declaration authorization.
+    # v1.2: http://goo.gl/PvwUXj#515-authorization-object
     class ResourceListingAuthorizationNode < Node
       GRANT_TYPES = [:implicit, :authorization_code].freeze
 
       def scope(&block)
         self.data[:scopes] ||= []
-        self.data[:scopes] << Swagger::Blocks::ScopeNode.call(&block)
+        self.data[:scopes] << Swagger::Blocks::ScopeNode.call(version: version, &block)
       end
 
       def grant_type(name, &block)
         raise ArgumentError.new("#{name} not in #{GRANT_TYPES}") if !GRANT_TYPES.include?(name)
         self.data[:grantTypes] ||= Swagger::Blocks::GrantTypesNode.new
+        self.data[:grantTypes].version = version
         self.data[:grantTypes].implicit(&block) if name == :implicit
         self.data[:grantTypes].authorization_code(&block) if name == :authorization_code
       end
     end
 
-    # http://goo.gl/PvwUXj#513-info-object
-    class InfoNode < Node; end
+    # v1.2: http://goo.gl/PvwUXj#513-info-object
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject
+    class InfoNode < Node
+      def contact(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:contact] = Swagger::Blocks::ContactNode.call(version: version, &block)
+      end
 
-    # http://goo.gl/PvwUXj#516-scope-object
+      def license(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:license] = Swagger::Blocks::LicenseNode.call(version: version, &block)
+      end
+    end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#contact-object
+    class ContactNode < Node; end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#license-object
+    class LicenseNode < Node; end
+
+    # v1.2: http://goo.gl/PvwUXj#516-scope-object
     class ScopeNode < Node; end
 
-    # http://goo.gl/PvwUXj#517-grant-types-object
+    # v1.2: http://goo.gl/PvwUXj#517-grant-types-object
     class GrantTypesNode < Node
       def implicit(&block)
-        self.data[:implicit] = Swagger::Blocks::ImplicitNode.call(&block)
+        self.data[:implicit] = Swagger::Blocks::ImplicitNode.call(version: version, &block)
       end
 
       def authorization_code(&block)
-        self.data[:authorization_code] = Swagger::Blocks::AuthorizationCodeNode.call(&block)
+        self.data[:authorization_code] = Swagger::Blocks::AuthorizationCodeNode.call(version: version, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#518-implicit-object
+    # v1.2: http://goo.gl/PvwUXj#518-implicit-object
     class ImplicitNode < Node
       def login_endpoint(&block)
-        self.data[:loginEndpoint] = Swagger::Blocks::LoginEndpointNode.call(&block)
+        self.data[:loginEndpoint] = Swagger::Blocks::LoginEndpointNode.call(version: version, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#5110-login-endpoint-object
+    # v1.2: http://goo.gl/PvwUXj#5110-login-endpoint-object
     class LoginEndpointNode < Node; end
 
-    # http://goo.gl/PvwUXj#519-authorization-code-object
+    # v1.2: http://goo.gl/PvwUXj#519-authorization-code-object
     class AuthorizationCodeNode < Node
       def token_request_endpoint(&block)
-        self.data[:tokenRequestEndpoint] = Swagger::Blocks::TokenRequestEndpointNode.call(&block)
+        self.data[:tokenRequestEndpoint] = Swagger::Blocks::TokenRequestEndpointNode.call(version: version, &block)
       end
 
       def token_endpoint(&block)
-        self.data[:tokenEndpoint] = Swagger::Blocks::TokenEndpointNode.call(&block)
+        self.data[:tokenEndpoint] = Swagger::Blocks::TokenEndpointNode.call(version: version, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#5111-token-request-endpoint-object
+    # v1.2: http://goo.gl/PvwUXj#5111-token-request-endpoint-object
     class TokenRequestEndpointNode < Node; end
 
-    # http://goo.gl/PvwUXj#5112-token-endpoint-object
+    # v1.2: http://goo.gl/PvwUXj#5112-token-endpoint-object
     class TokenEndpointNode < Node; end
 
     # -----
-    # Nodes for API Declarations.
+    # v1.2: Nodes for API Declarations.
     # -----
 
-    # http://goo.gl/PvwUXj#52-api-declaration
+    # v1.2: http://goo.gl/PvwUXj#52-api-declaration
     class ApiDeclarationNode < Node
       def api(&block)
         self.data[:apis] ||= []
@@ -283,7 +447,7 @@ module Swagger
         # http://goo.gl/PvwUXj#522-api-object
         # - The API Object describes one or more operations on a single path. In the apis array,
         #   there MUST be only one API Object per path.
-        temp_api_node = Swagger::Blocks::ApiNode.call(&block)
+        temp_api_node = Swagger::Blocks::ApiNode.call(version: version, &block)
         api_node = self.data[:apis].select do |api|
           api.data[:path] == temp_api_node.data[:path]
         end[0]  # Embrace Ruby wtfs.
@@ -298,45 +462,104 @@ module Swagger
       end
     end
 
-    # http://goo.gl/PvwUXj#522-api-object
+    # v1.2: http://goo.gl/PvwUXj#522-api-object
     class ApiNode < Node
       def operation(&block)
         self.data[:operations] ||= []
-        self.data[:operations] << Swagger::Blocks::OperationNode.call(&block)
+        self.data[:operations] << Swagger::Blocks::OperationNode.call(version: version, &block)
       end
     end
 
+    # 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, &block)
+        op = op.to_sym
+        raise ArgumentError.new("#{name} not in #{OPERATION_TYPES}") if !OPERATION_TYPES.include?(op)
+        self.data[op] = Swagger::Blocks::OperationNode.call(version: version, &block)
+      end
+    end
+
+    # v1.2: http://goo.gl/PvwUXj#523-operation-object
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object
     class OperationNode < Node
+
       def parameter(&block)
         self.data[:parameters] ||= []
-        self.data[:parameters] << Swagger::Blocks::ParameterNode.call(&block)
+        self.data[:parameters] << Swagger::Blocks::ParameterNode.call(version: version, &block)
       end
 
       def response_message(&block)
+        raise NotSupportedError unless is_swagger_1_2?
+
         self.data[:responseMessages] ||= []
-        self.data[:responseMessages] << Swagger::Blocks::Node.call(&block)
+        self.data[:responseMessages] << Swagger::Blocks::Node.call(version: version, &block)
       end
 
       def authorization(name, &block)
+        raise NotSupportedError unless is_swagger_1_2?
+
         self.data[:authorizations] ||= Swagger::Blocks::ApiAuthorizationsNode.new
+        self.data[:authorizations].version = version
         self.data[:authorizations].authorization(name, &block)
       end
 
       def items(&block)
-        self.data[:items] = Swagger::Blocks::ItemsNode.call(&block)
+        raise NotSupportedError unless is_swagger_1_2?
+
+        self.data[:items] = Swagger::Blocks::ItemsNode.call(version: version, &block)
+      end
+
+      def response(resp, &block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        # TODO validate 'resp' is as per spec
+        self.data[:responses] ||= {}
+        self.data[:responses][resp] = Swagger::Blocks::ResponseNode.call(version: version, &block)
+      end
+
+      def externalDocs(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:externalDocs] = Swagger::Blocks::ExternalDocsNode.call(version: version, &block)
+      end
+
+      def security(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:security] ||= []
+        self.data[:security] << Swagger::Blocks::SecurityRequirementNode.call(version: version, &block)
+      end
+    end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#externalDocumentationObject
+    class ExternalDocsNode < Node; end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityRequirementObject
+    class SecurityRequirementNode < Node; end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-scheme-object
+    class SecuritySchemeNode < Node
+      # TODO support ^x- Vendor Extensions
+
+      def scope(name, description)
+        self.data[:scopes] ||= {}
+        self.data[:scopes][name] = description
       end
     end
 
-    # NOTE: in the spec this is different than Resource Listing's authorizations.
-    # http://goo.gl/PvwUXj#514-authorizations-object
+    # v1.2: NOTE: in the spec this is different than Resource Listing's authorizations.
+    # v1.2: http://goo.gl/PvwUXj#514-authorizations-object
     class ApiAuthorizationsNode < Node
       def authorization(name, &block)
-        self.data[name] ||= Swagger::Blocks::ApiAuthorizationNode.call(&block)
+        self.data[name] ||= Swagger::Blocks::ApiAuthorizationNode.call(version: version, &block)
       end
     end
 
-    # NOTE: in the spec this is different than Resource Listing's authorization.
-    # http://goo.gl/PvwUXj#515-authorization-object
+    # v1.2: NOTE: in the spec this is different than Resource Listing's authorization.
+    # v1.2: http://goo.gl/PvwUXj#515-authorization-object
     class ApiAuthorizationNode < Node
       def as_json
         # Special case: the API Authorization object is weirdly the only array of hashes.
@@ -347,55 +570,174 @@ module Swagger
 
       def scope(&block)
         self.data[:_scopes] ||= []
-        self.data[:_scopes] << Swagger::Blocks::ApiAuthorizationScopeNode.call(&block)
+        self.data[:_scopes] << Swagger::Blocks::ApiAuthorizationScopeNode.call(version: version, &block)
       end
     end
 
-    # NOTE: in the spec this is different than Resource Listing's scope object.
-    # http://goo.gl/PvwUXj#5211-scope-object
+    # v1.2: NOTE: in the spec this is different than Resource Listing's scope object.
+    # v1.2: http://goo.gl/PvwUXj#5211-scope-object
     class ApiAuthorizationScopeNode < Node; end
 
-    # http://goo.gl/PvwUXj#434-items-object
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responseObject
+    class ResponseNode < Node
+      def schema(&block)
+        self.data[:schema] = Swagger::Blocks::SchemaNode.call(version: version, &block)
+      end
+
+      def header(head, &block)
+        # TODO validate 'head' is as per spec
+        self.data[:headers] ||= {}
+        self.data[:headers][head] = Swagger::Blocks::HeaderNode.call(version: version, &block)
+      end
+
+      def example(exam, &block)
+        # TODO validate 'exam' is as per spec
+        self.data[:examples] ||= {}
+        self.data[:examples][exam] = Swagger::Blocks::ExampleNode.call(version: version, &block)
+      end
+    end
+
+    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(&block)
+        data << Swagger::Blocks::SchemaNode.call(version: version, &block)
+      end
+    end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema-object
+    class SchemaNode < Node
+      def items(&block)
+        self.data[:items] = Swagger::Blocks::ItemsNode.call(version: version, &block)
+      end
+
+      def allOf(&block)
+        self.data[:allOf] = Swagger::Blocks::AllOfNode.call(version: version, &block)
+      end
+
+      def property(name, &block)
+        self.data[:properties] ||= Swagger::Blocks::PropertiesNode.new
+        self.data[:properties].version = version
+        self.data[:properties].property(name, &block)
+      end
+
+      def xml(&block)
+        self.data[:xml] = Swagger::Blocks::XmlNode.call(version: version, &block)
+      end
+
+      def externalDocs(&block)
+        self.data[:externalDocs] = Swagger::Blocks::ExternalDocsNode.call(version: version, &block)
+      end
+    end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#headerObject
+    class HeaderNode < Node
+      def items(&block)
+        self.data[:items] = Swagger::Blocks::ItemsNode.call(version: version, &block)
+      end
+    end
+
+    # v2.0:
+    class XmlNode < Node; end
+
+    # v2.0:
+    class ExampleNode < Node; end
+
+    # v1.2:
+    # v2.0:
     class ItemsNode < Node; end
 
-    # http://goo.gl/PvwUXj#524-parameter-object
-    class ParameterNode < Node; end
+    # v1.2: http://goo.gl/PvwUXj#524-parameter-object
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object
+    class ParameterNode < Node
+      def schema(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:schema] = Swagger::Blocks::SchemaNode.call(version: version, &block)
+      end
+
+      def items(&block)
+        raise NotSupportedError unless is_swagger_2_0?
+
+        self.data[:items] = Swagger::Blocks::ItemsNode.call(version: version, &block)
+      end
+    end
+
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tag-object
+    class TagNode < Node
+
+      # TODO support ^x- Vendor Extensions
+
+      def externalDocs(&block)
+        self.data[:externalDocs] = Swagger::Blocks::ExternalDocsNode.call(version: version, &block)
+      end
+    end
 
     # -----
-    # Nodes for Models.
+    # v1.2: Nodes for Models.
     # -----
 
-    # http://goo.gl/PvwUXj#526-models-object
+    # v1.2: http://goo.gl/PvwUXj#526-models-object
     class ModelsNode < Node
       def merge!(other_models_node)
         self.data.merge!(other_models_node.data)
       end
 
       def model(name, &block)
-        self.data[name] ||= Swagger::Blocks::ModelNode.call(&block)
+        self.data[name] ||= Swagger::Blocks::ModelNode.call(version: version, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#527-model-object
+    # v1.2: http://goo.gl/PvwUXj#527-model-object
     class ModelNode < Node
       def property(name, &block)
         self.data[:properties] ||= Swagger::Blocks::PropertiesNode.new
+        self.data[:properties].version = version
         self.data[:properties].property(name, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#527-model-object
+    # v1.2: http://goo.gl/PvwUXj#527-model-object
     class PropertiesNode < Node
       def property(name, &block)
-        self.data[name] = Swagger::Blocks::PropertyNode.call(&block)
+        self.data[name] = Swagger::Blocks::PropertyNode.call(version: version, &block)
       end
     end
 
-    # http://goo.gl/PvwUXj#527-model-object
+    # v1.2: http://goo.gl/PvwUXj#527-model-object
     class PropertyNode < Node
       def items(&block)
-        self.data[:items] = Swagger::Blocks::ItemsNode.call(&block)
+        self.data[:items] = Swagger::Blocks::ItemsNode.call(version: version, &block)
       end
     end
   end
-end
+end