sinatra-swagger-exposer-ng 0.5.0

data/lib/sinatra/swagger-exposer/configuration/swagger-hash-like.rb

@@ -0,0 +1,45 @@
+require_relative '../swagger-invalid-exception'
+
+require_relative 'swagger-configuration-utilities'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      # A hash-like for groups of things
+      class SwaggerHashLike
+
+        include SwaggerConfigurationUtilities
+
+        def initialize(things)
+          @things = things
+        end
+
+        def [](name)
+          @things[name]
+        end
+
+        def key?(name)
+          @things.key? name
+        end
+
+        def check_duplicate(name, type_name)
+          if key?(name)
+            raise SwaggerInvalidException.new("#{type_name} [#{name}] already exist with value #{@things[name]}")
+          end
+        end
+
+        def to_swagger
+          if @things.empty?
+            nil
+          else
+            hash_to_swagger(@things)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-info.rb

@@ -0,0 +1,73 @@
+require_relative '../swagger-invalid-exception'
+
+require_relative 'swagger-configuration-utilities'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      # The info declaration
+      class SwaggerInfo
+
+        include SwaggerConfigurationUtilities
+
+        def initialize(values)
+          @values = process(values, 'info', INFO_FIELDS, values)
+        end
+
+        # Known fields for the info field
+        INFO_FIELDS = {
+          :version => String,
+          :title => String,
+          :description => String,
+          :termsOfService => String,
+          :contact => {:name => String, :email => String, :url => String},
+          :license => {:name => String, :url => String},
+        }
+
+        # Recursive function
+        def process(current_hash, current_field_name, current_fields, top_level_hash)
+          result = {}
+
+          current_hash.each_pair do |current_key, current_value|
+            key_sym = current_key.to_sym
+            if current_fields.key? key_sym
+
+              field_content = current_fields[key_sym]
+              if field_content == String
+                if current_value.is_a? String
+                  result[key_sym] = current_value
+                else
+                  raise SwaggerInvalidException.new("Property [#{current_key}] value [#{current_value}] should be a String for #{current_field_name}: #{top_level_hash}")
+                end
+              else
+                if current_value.is_a? Hash
+                  sub_params = process(current_value, current_field_name, field_content, top_level_hash)
+                  if sub_params
+                    result[key_sym] = sub_params
+                  end
+                else
+                  raise SwaggerInvalidException.new("Property [#{current_key}] value [#{current_value}] should be a Hash for #{current_field_name}: #{top_level_hash}")
+                end
+              end
+            else
+              raise SwaggerInvalidException.new("Unknown property [#{current_key}] for #{current_field_name}#{list_or_none(current_fields.keys, 'values')}")
+            end
+          end
+          result.empty? ? nil : result
+        end
+
+        def to_swagger
+          @values
+        end
+
+        def to_s
+          @values.to_json
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-parameter-validation-helper.rb

@@ -0,0 +1,106 @@
+require_relative '../swagger-parameter-helper'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      # Helper for validating parameters
+      module SwaggerParameterValidationHelper
+
+        include Sinatra::SwaggerExposer::SwaggerParameterHelper
+
+        # Validate parameters
+        # @param type [String] the parameter type
+        # @param params [Hash]
+        def validate_params(type, params)
+          validate_limit_parameters(type, params)
+          validate_length_parameters(type, params)
+        end
+
+        # Test if a parameter is a boolean
+        # @param name the parameter's name
+        # @param value value the parameter's value
+        # @return [NilClass]
+        def check_boolean(name, value)
+          unless [true, false].include? value
+            raise SwaggerInvalidException.new("Invalid boolean value [#{value}] for [#{name}]")
+          end
+        end
+
+        # Validate the limit parameters
+        # @param type [String] the parameter type
+        # @param params [Hash] the parameters
+        def validate_limit_parameters(type, params)
+          max = validate_limit_parameter(type, params, PARAMS_MAXIMUM, PARAMS_EXCLUSIVE_MAXIMUM)
+          min = validate_limit_parameter(type, params, PARAMS_MINIMUM, PARAMS_EXCLUSIVE_MINIMUM)
+          if min && max && (max < min)
+            raise SwaggerInvalidException.new("Minimum value [#{min}] can't be more than maximum value [#{max}]")
+          end
+        end
+
+        # Validate a limit param like maximum and exclusiveMaximum
+        # @param type [String] the parameter type
+        # @param params [Hash] the parameters
+        # @param limit_param_name [Symbol] the limit parameter name
+        # @param exclusive_limit_param_name [Symbol] the exclusive limit parameter name
+        def validate_limit_parameter(type, params, limit_param_name, exclusive_limit_param_name)
+          parameter_value = nil
+          if params.key? limit_param_name
+            unless [TYPE_INTEGER, TYPE_NUMBER].include? @type
+              raise SwaggerInvalidException.new("Parameter #{limit_param_name} can only be specified for types #{TYPE_INTEGER} or #{TYPE_NUMBER} and not for [#{@type}]")
+            end
+            parameter_value = params[limit_param_name]
+            unless parameter_value.is_a? Numeric
+              raise SwaggerInvalidException.new("Parameter #{limit_param_name} must be a numeric and can not be [#{parameter_value}]")
+            end
+          end
+
+          if params.key? exclusive_limit_param_name
+            check_boolean(exclusive_limit_param_name, params[exclusive_limit_param_name])
+            unless params.key? limit_param_name
+              raise SwaggerInvalidException.new("You can't have a #{exclusive_limit_param_name} value without a #{limit_param_name}")
+            end
+          end
+          parameter_value
+        end
+
+        # Validate the length parameters minLength and maxLength
+        # @param type [String] the parameter type
+        # @param params [Hash] the parameters
+        def validate_length_parameters(type, params)
+          min_length = validate_length_parameter(type, params, PARAMS_MIN_LENGTH)
+          max_length = validate_length_parameter(type, params, PARAMS_MAX_LENGTH)
+
+          if min_length && max_length && (max_length < min_length)
+            raise SwaggerInvalidException.new("Minimum length #{min_length} can't be more than maximum length #{max_length}")
+          end
+        end
+
+        # Validate a length param like minLength and maxLength
+        # @param type [String] the parameter type
+        # @param params [Hash] the parameters
+        # @param length_param_name [Symbol] the length parameter name
+        # @return [Integer] the parameter value if it is present
+        def validate_length_parameter(type, params, length_param_name)
+          if params.key? length_param_name
+            if type == TYPE_STRING
+              parameter_value = params[length_param_name]
+              unless parameter_value.is_a? Integer
+                raise SwaggerInvalidException.new("Parameter #{length_param_name} must be an integer and can not be [#{parameter_value}]")
+              end
+              parameter_value
+            else
+              raise SwaggerInvalidException.new("Parameter #{length_param_name} can only be specified for type #{TYPE_STRING} and not for [#{@type}]")
+            end
+
+          else
+            nil
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-response-header.rb

@@ -0,0 +1,68 @@
+require_relative '../swagger-invalid-exception'
+
+require_relative 'swagger-parameter-validation-helper'
+require_relative 'swagger-type-property'
+require_relative 'swagger-configuration-utilities'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      class SwaggerResponseHeader
+
+        include SwaggerConfigurationUtilities
+        include SwaggerParameterValidationHelper
+
+        attr_reader :type, :name, :description
+
+        PRIMITIVE_HEADERS_TYPES = [
+          TYPE_STRING,
+          TYPE_NUMBER,
+          TYPE_INTEGER,
+          TYPE_BOOLEAN,
+        ]
+
+        # Create a new instance
+        # @param name [String] the name
+        # @param description [String] the description
+        # @param type [String] the type name
+        def initialize(name, type, description)
+          check_name(name)
+          @name = name
+
+          if description
+            @description = description
+          end
+
+          get_type(type, PRIMITIVE_HEADERS_TYPES)
+        end
+
+
+        # Return the swagger version
+        # @return [Hash]
+        def to_swagger
+          result = {
+            :type => @type,
+          }
+
+          if @description
+            result[:description] = @description
+          end
+
+          result
+        end
+
+        def to_s
+          {
+            :name => @name,
+            :type => @type,
+            :description => @description,
+          }.to_json
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-response-headers.rb

@@ -0,0 +1,33 @@
+require_relative 'swagger-hash-like'
+require_relative 'swagger-response-header'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      # Contain all the declared response headers
+      class SwaggerResponseHeaders < SwaggerHashLike
+
+        attr_reader :response_headers
+
+        def initialize
+          @response_headers = {}
+          super(@response_headers)
+        end
+
+        # Add a new swagger response header
+        # @param name [String] the type name
+        # @param type [Object] the type
+        # @param description [String] the description
+        def add_response_header(name, type, description)
+          name = name.to_s
+          check_duplicate(name, 'Response header')
+          @response_headers[name] = SwaggerResponseHeader.new(name, type, description)
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-type-property.rb

@@ -0,0 +1,83 @@
+require_relative '../swagger-invalid-exception'
+
+require_relative 'swagger-configuration-utilities'
+require_relative 'swagger-parameter-validation-helper'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+      # A property of a type
+      class SwaggerTypeProperty
+
+        attr_reader :name, :type, :items
+
+        include SwaggerConfigurationUtilities
+        include SwaggerParameterValidationHelper
+
+        OTHER_PROPERTIES = [:example, :description, :format, :minLength, :maxLength, :default]
+        PROPERTIES = [:type] + OTHER_PROPERTIES
+
+        def initialize(type_name, property_name, property_properties, known_types)
+          @name = property_name
+
+          unless property_properties.is_a? Hash
+            raise SwaggerInvalidException.new("Property [#{property_name}] value [#{property_properties}] of [#{type_name}] should be a hash")
+          end
+
+          if property_properties.key? :type
+            get_type(property_properties[:type], PRIMITIVE_TYPES + known_types)
+          end
+
+          white_list_params(property_properties, PROPERTIES)
+
+          validate_params(@type, property_properties)
+
+          @other_properties = property_properties.select do |key, value|
+            OTHER_PROPERTIES.include? key
+          end
+        end
+
+        def properties
+          @other_properties
+        end
+
+        def to_swagger
+          result = @other_properties.clone
+
+          if @type
+            if @type == TYPE_ARRAY
+              result[:type] = TYPE_ARRAY
+              if @items
+                if PRIMITIVE_TYPES.include? @items
+                  result[:items] = {:type => @items}
+                else
+                  result[:items] = ref_to_type(@items)
+                end
+              end
+            else
+              if PRIMITIVE_TYPES.include? @type
+                result[:type] = @type
+              else
+                result['$ref'] = "#/definitions/#{@type}"
+              end
+            end
+          end
+
+          result
+        end
+
+        def to_s
+          {
+            :name => @name,
+            :type => @type,
+            :items => @items,
+            :other_properties => @other_properties,
+          }.to_json
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-type.rb

@@ -0,0 +1,128 @@
+require_relative '../swagger-invalid-exception'
+
+require_relative 'swagger-configuration-utilities'
+require_relative 'swagger-type-property'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+      # A type
+      class SwaggerType
+
+        attr_reader :properties, :required, :extends
+
+        include SwaggerConfigurationUtilities
+
+        PROPERTY_PROPERTIES = :properties
+        PROPERTY_REQUIRED = :required
+        PROPERTY_EXAMPLE = :example
+        PROPERTY_EXTENDS = :extends
+        PROPERTIES = [PROPERTY_PROPERTIES, PROPERTY_REQUIRED, PROPERTY_EXAMPLE, PROPERTY_EXTENDS]
+
+        def initialize(type_name, type_properties, known_types)
+          white_list_params(type_properties, PROPERTIES)
+          @properties = process_properties(type_name, type_properties, known_types)
+          @required = process_required(type_name, type_properties, @properties.keys)
+          @example = process_example(type_name, type_properties, @properties.keys)
+          @extends = process_extends(type_properties, known_types)
+        end
+
+        def process_properties(type_name, type_content, known_types)
+          possible_value = check_attribute_empty_or_bad(type_name, type_content, PROPERTY_PROPERTIES, Hash)
+          if possible_value
+            possible_value
+          else
+            result = {}
+            type_content[PROPERTY_PROPERTIES].each_pair do |property_name, property_properties|
+              result[property_name.to_s] = SwaggerTypeProperty.new(type_name, property_name, property_properties, known_types)
+            end
+            result
+          end
+        end
+
+        def process_required(type_name, type_content, properties_names)
+          possible_value = check_attribute_empty_or_bad(type_name, type_content, PROPERTY_REQUIRED, Array)
+          if possible_value
+            possible_value
+          else
+            type_content[PROPERTY_REQUIRED].each do |property_name|
+              property_name = property_name.to_s
+              unless properties_names.include? property_name
+                raise SwaggerInvalidException.new("Required property [#{property_name}] of [#{type_name}] is unknown#{list_or_none(properties_names, 'properties')}")
+              end
+            end
+            type_content[PROPERTY_REQUIRED]
+          end
+        end
+
+        def process_example(type_name, type_content, properties_names)
+          possible_value = check_attribute_empty_or_bad(type_name, type_content, PROPERTY_EXAMPLE, Hash)
+          if possible_value
+            possible_value
+          else
+            type_content[PROPERTY_EXAMPLE].each_pair do |property_name, property_value|
+              property_name = property_name.to_s
+              unless properties_names.include? property_name
+                raise SwaggerInvalidException.new("Example property [#{property_name}] with value [#{property_value}] of [#{type_name}] is unknown#{list_or_none(properties_names, 'properties')}")
+              end
+            end
+            type_content[PROPERTY_EXAMPLE]
+          end
+        end
+
+        def check_attribute_empty_or_bad(type_name, type_content, attribute_name, attribute_class)
+          if !type_content.key?(attribute_name)
+            attribute_class.new
+          elsif !type_content[attribute_name].is_a? attribute_class
+            raise SwaggerInvalidException.new("Attribute [#{attribute_name}] of #{type_name} is not an hash: #{type_content[attribute_name]}")
+          end
+        end
+
+        def process_extends(type_properties, known_types)
+          if type_properties.key? PROPERTY_EXTENDS
+            check_type(type_properties[PROPERTY_EXTENDS], known_types)
+            @extends = type_properties[PROPERTY_EXTENDS]
+          end
+        end
+
+        def to_swagger
+          result = {:type => 'object'}
+
+          unless @properties.empty?
+            result[PROPERTY_PROPERTIES] = hash_to_swagger(@properties)
+          end
+
+          unless @required.empty?
+            result[PROPERTY_REQUIRED] = @required
+          end
+
+          unless @example.empty?
+            result[PROPERTY_EXAMPLE] = @example
+          end
+
+          if @extends
+            result = {
+              :allOf => [
+                ref_to_type(@extends),
+                result
+              ]
+            }
+          end
+
+          result
+        end
+
+        def to_s
+          {
+            :properties => @properties,
+            :required => @required,
+            :example => @example,
+          }.to_json
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/configuration/swagger-types.rb

@@ -0,0 +1,35 @@
+require_relative 'swagger-hash-like'
+require_relative 'swagger-type'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      # Contain all the declared types
+      class SwaggerTypes < SwaggerHashLike
+
+        attr_reader :types
+
+        def initialize
+          @types = {}
+          super(types)
+        end
+
+        # Add a new swagger type
+        # @param name [String] the type name
+        # @param params [Hash] the type params
+        def add_type(name, params)
+          check_duplicate(name, 'Type')
+          @types[name] = SwaggerType.new(name, params, @types.keys)
+        end
+
+        def types_names
+          @types.keys
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/processing/swagger-array-value-processor.rb

@@ -0,0 +1,46 @@
+require_relative '../swagger-parameter-helper'
+require_relative '../swagger-invalid-exception'
+require_relative 'swagger-base-value-processor'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Processing
+
+      # Validate arrays
+      class SwaggerArrayValueProcessor < SwaggerBaseValueProcessor
+
+        include Sinatra::SwaggerExposer::SwaggerParameterHelper
+
+        attr_reader :processor_for_values
+
+        # Initialize
+        # @param name [String] the name
+        # @param required [TrueClass] if the parameter is required
+        # @param processor_for_values [Sinatra::SwaggerExposer::Processing::SwaggerBaseValueProcessor] processor for the values
+        def initialize(name, required, processor_for_values)
+          super(name, required, nil)
+          @processor_for_values = processor_for_values
+        end
+
+        def useful?
+          true
+        end
+
+        def validate_value(value)
+          if value
+            if value.is_a? Array
+              value.collect { |i| @processor_for_values.validate_value(i) }
+            else
+              raise SwaggerInvalidException.new("Value [#{name}] should be an array but is [#{value}]")
+            end
+          else
+            nil
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/processing/swagger-base-value-processor.rb

@@ -0,0 +1,50 @@
+require_relative '../swagger-parameter-helper'
+require_relative '../swagger-invalid-exception'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Processing
+
+      # Base class for value processor
+      class SwaggerBaseValueProcessor
+
+        attr_reader :name, :required
+
+        include Sinatra::SwaggerExposer::SwaggerParameterHelper
+
+        # Initialize
+        # @param name [String] the name
+        # @param required [TrueClass] if the parameter is required
+        # @param default [Object] the default value
+        def initialize(name, required, default)
+          @name = name.to_s
+          @required = required
+          @default = default
+        end
+
+        # Test if the processor is useful
+        # @return [TrueClass]
+        def useful?
+          @required || (!@default.nil?)
+        end
+
+        def process(params)
+          unless params.is_a? Hash
+            raise SwaggerInvalidException.new("Value [#{@name}] should be an object but is a [#{params.class}]")
+          end
+          if params.key?(@name) && (!params[@name].nil?)
+            params[@name] = validate_value(params[@name])
+          elsif @required
+            raise SwaggerInvalidException.new("Mandatory value [#{@name}] is missing")
+          elsif @default
+            params[@name] = @default
+          end
+          params
+        end
+
+      end
+    end
+  end
+end