sinatra-swagger-exposer 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b55ef98d692d8d3d3b6d27a92b7a30657d5729bb
-  data.tar.gz: a34f58471cf590358e549b51ac348829b269b1ae
+  metadata.gz: fa97395699d5708bb599a1793df03d11ee73cc6a
+  data.tar.gz: 8dcad9fd2667784b9a6ba79362e6109b344779d8
 SHA512:
-  metadata.gz: fe4a2405064efbde281a34810dc78680a3a4ba484cc281f3045ef12211cf8470baadb171db8bb6fdfd53faa11bbb178a3cd3d60a3deb21283bcac17cff3af910
-  data.tar.gz: 86f6a2d376446ed4a59e5d1049955f1cacc2eb0334895d116ab42fcdd891618863a30b5264ec81983d7ff3c453ad4e446dc9de4bb3c5bdb8cef4773c39d7eaca
+  metadata.gz: ea832406300901d1975504d66725fec8669f465756c75abf68fdf8e3a58af5a3a530659acb50887c2ebceccd0b9287daf89cfc4e769a3365659b05bd53d16a76
+  data.tar.gz: 995af3f7a7e77b2ba82ef9644856d324b9f96cc8acf582f8fdd448f3f69ebcee34a44075ae1c84fd7a066bce44ea2af4fdf59fe681554a129d88e0017fbd6834

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# 0.1.0
+
+- Added verification and enrichment form params
+- Added type extends
+- Added validation for min and max value
+
+# 0.0.1
+
+- First version

data/README.md

@@ -0,0 +1,97 @@
+# Sinatra::SwaggerExposer
+
+[![Code Climate](https://codeclimate.com/github/archiloque/sinatra-swagger-exposer/badges/gpa.svg)](https://codeclimate.com/github/archiloque/sinatra-swagger-exposer)
+[![Build Status](https://travis-ci.org/archiloque/sinatra-swagger-exposer.svg?branch=master)](https://travis-ci.org/archiloque/sinatra-swagger-exposer)
+[![Coverage Status](https://coveralls.io/repos/archiloque/sinatra-swagger-exposer/badge.svg?branch=master)](https://coveralls.io/r/archiloque/sinatra-swagger-exposer?branch=master)
+
+Create Swagger endpoint for your Sinatra application.
+
+This Sinatra extension enable you to add metadata to your code to
+
+- expose your API as a [Swagger](http://swagger.io) endpoint.
+- validate and enrich the invocation parameters
+
+I'm adding features as I need them and it currently doesn't use all the Swagger options, so if you need one that is missing please open an issue.
+
+## Design choices
+
+- All the declarations are validated when the server is started
+- The declarations are defined to look as ruby-ish as possible
+- Declarations are used for parameters validation and enrichment
+
+## Usage
+
+To use it in your app :
+
+```ruby
+require 'sinatra/swagger-exposer/swagger-exposer'
+
+class MyApp < Sinatra::Base
+
+  register Sinatra::SwaggerExposer
+
+  general_info(
+      {
+          version: '0.0.1',
+          title: 'My app',
+          description: 'My wonderful app',
+          license: {
+              name: 'MIT',
+              url: 'http://opensource.org/licenses/MIT'
+          }
+      }
+  )
+
+  type 'Status',
+               {
+                   :properties => {
+                       :status => {
+                           :type => String,
+                           :example => 'OK,
+                       },
+                   },
+                   :required => [:status]
+               }
+
+  endpoint_description 'Base method to ping'
+  endpoint_response 200, 'Status', 'Standard response'
+  endpoint_tags 'Ping'
+  get '/' do
+    json({'status' => 'OK'})
+  end
+
+end
+```
+
+The swagger json endpoint will be exposed at `/swagger_doc.json`.
+
+## Detailed example
+
+A more complete example is available [here](https://github.com/archiloque/sinatra-swagger-exposer/tree/master/example).
+
+## About swagger-ui
+
+- If you to use [swagger-ui](https://github.com/swagger-api/swagger-ui) with your app you will need to add croo-origin setup.
+The easiest way is to use the [sinatra-cross_origin](https://github.com/britg/sinatra-cross_origin) gem. Fro a simple sample you can have a look at [example application](https://github.com/archiloque/sinatra-swagger-exposer/tree/master/example).
+- Swagger-ui doesn't work with all the swagger features
+  - Some of them like parameters maximum and minimum values are ignored
+  - Some of them like extending types make the endpoint unusable
+
+## Changes
+
+Changelog is [here](https://github.com/archiloque/sinatra-swagger-exposer/blob/master/CHANGELOG.md).
+
+## Resources
+
+- [Swagger RESTful API Documentation Specification](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md).
+- [Swagger json examples](https://github.com/swagger-api/swagger-spec/tree/master/examples/v2.0/json).
+- [The swagger json schema](https://raw.githubusercontent.com/swagger-api/swagger-spec/master/schemas/v2.0/schema.json).
+
+## Todo
+
+- More parameters taken into account
+- More validations where possible
+
+## License
+
+This software is released under the MIT license.

data/example/petstore.rb

@@ -74,28 +74,71 @@ class Petstore < Sinatra::Base
                     },
                 },
             }
+  type 'Cat', {
+                # Not yet supported in swagger-ui, see https://github.com/swagger-api/swagger-js/issues/188
+                :extends => 'Pet',
+                :properties => {
+                    :fluffy => {
+                        :type => TrueClass,
+                        :description => 'is this cat fluffy ?',
+                        :example => true,
+                    },
+                },
+            }
 
   endpoint_summary 'Finds all the pets'
   endpoint_description 'Returns all pets from the system that the user has access to'
   endpoint_tags 'Pets'
   endpoint_response 200, ['Pet'], 'Standard response'
+  endpoint_parameter :size, 'The number of pets to return', :query, false, Integer,
+                     {
+                        :example => 100,
+                        :default => 20, # If the caller send no value the default value will be set in the params
+                        :maximum => 100,
+                        :minimum => 0,
+                        :exclusiveMinimum => true,
+                     }
   get '/pets' do
     content_type :json
     [].to_json
   end
 
+  endpoint_summary 'Finds all the cats'
+  endpoint_description 'Returns all cats from the system that the user has access to'
+  endpoint_tags 'Cats'
+  endpoint_response 200, ['Cat'], 'Standard response'
+  endpoint_parameter :size, 'The number of cats to return', :query, false, Integer,
+                     {
+                         :example => 100,
+                         :default => 20, # If the caller send no value the default value will be set in the params
+                         :maximum => 100,
+                         :minimum => 0,
+                         :exclusiveMinimum => true,
+                     }
+  get '/cats' do
+    content_type :json
+    [].to_json
+  end
+
   endpoint_summary 'Finds a pet by its id'
   endpoint_description 'Finds a pet by its id, or 404 if the user does not have access to the pet'
   endpoint_tags 'Pets'
   endpoint_response 200, 'Pet', 'Standard response'
   endpoint_response 404, 'Error', 'Pet not found'
-  endpoint_parameter :id, 'The pet id', :path, true, String
-                 {
-                     :example => 'AMZ',
-                 }
+  endpoint_parameter :id, 'The pet id', :path, true, Integer, # Will fail if a non-numerical value is used
+                     {
+                         :example => 1234,
+                     }
   get '/pets/:id' do
     content_type :json
-    [404, {:code => 404, :message => 'Pet not found'}]
+    [404, {:code => 404, :message => 'Pet not found'}.to_json]
+  end
+
+  # See https://github.com/britg/sinatra-cross_origin/issues/18
+  options '*' do
+    response.headers['Allow'] = 'HEAD,GET,PUT,POST,DELETE,OPTIONS'
+    response.headers['Access-Control-Allow-Headers'] = 'X-Requested-With, X-HTTP-Method-Override, Content-Type, Cache-Control, Accept'
+    200
   end
 
 end

data/lib/sinatra/swagger-exposer/swagger-endpoint-parameter.rb

@@ -1,4 +1,5 @@
 require_relative 'swagger-invalid-exception'
+require_relative 'swagger-parameter-preprocessor'
 require_relative 'swagger-utilities'
 
 module Sinatra
@@ -10,8 +11,33 @@ module Sinatra
       include SwaggerUtilities
 
       HOW_TO_PASS_BODY = 'body'
-      HOW_TO_PASS= ['path', 'query', 'header', 'formData'] + [HOW_TO_PASS_BODY]
-      PRIMITIVE_TYPES_FOR_NON_BODY = ['string', 'number', 'integer', 'boolean']
+      HOW_TO_PASS_HEADER = 'header'
+      HOW_TO_PASS_PATH = 'path'
+      HOW_TO_PASS_QUERY = 'query'
+      HOW_TO_PASS = [HOW_TO_PASS_PATH, HOW_TO_PASS_QUERY, HOW_TO_PASS_HEADER, 'formData', HOW_TO_PASS_BODY]
+
+      TYPE_INTEGER = 'integer'
+      TYPE_BOOLEAN = 'boolean'
+      TYPE_NUMBER = 'number'
+      TYPE_STRING = 'string'
+      PRIMITIVE_TYPES_FOR_NON_BODY = [TYPE_STRING, TYPE_NUMBER, TYPE_INTEGER, TYPE_BOOLEAN]
+
+      PARAMS_FORMAT = :format
+      PARAMS_DEFAULT = :default
+      PARAMS_EXAMPLE = :example
+      PARAMS_MAXIMUM = :maximum
+      PARAMS_MINIMUM = :minimum
+      PARAMS_EXCLUSIVE_MINIMUM = :exclusiveMinimum
+      PARAMS_EXCLUSIVE_MAXIMUM = :exclusiveMaximum
+      PARAMS_LIST = [
+          PARAMS_FORMAT,
+          PARAMS_DEFAULT,
+          PARAMS_EXAMPLE,
+          PARAMS_MAXIMUM,
+          PARAMS_MINIMUM,
+          PARAMS_EXCLUSIVE_MINIMUM,
+          PARAMS_EXCLUSIVE_MAXIMUM,
+      ]
 
       def initialize(name, description, how_to_pass, required, type, params, known_types)
         unless name.is_a?(String) || name.is_a?(Symbol)
@@ -29,7 +55,7 @@ module Sinatra
 
         how_to_pass = how_to_pass.to_s
         unless HOW_TO_PASS.include? how_to_pass
-          raise SwaggerInvalidException.new("Unknown how to pass value [#{how_to_pass}], registered types are #{HOW_TO_PASS.join(', ')}")
+          raise SwaggerInvalidException.new("Unknown how to pass value [#{how_to_pass}]#{list_or_none(HOW_TO_PASS, 'registered types')}")
         end
         @how_to_pass = how_to_pass
 
@@ -44,11 +70,20 @@ module Sinatra
         end
         @required = required
 
-        if params
-          white_list_params(params, [:format])
-        end
+        white_list_params(params, PARAMS_LIST)
+        validate_params(params)
         @params = params
+      end
 
+      # Validate parameters
+      # @param params [Hash]
+      def validate_params(params)
+        validate_limit_parameter(params, PARAMS_MAXIMUM, PARAMS_EXCLUSIVE_MAXIMUM)
+        validate_limit_parameter(params, PARAMS_MINIMUM, PARAMS_EXCLUSIVE_MINIMUM)
+      end
+
+      def preprocessor
+        SwaggerParameterPreprocessor.new(@name, @how_to_pass, @required, @type, @params[:default], @params)
       end
 
       def to_swagger
@@ -65,14 +100,14 @@ module Sinatra
               if PRIMITIVE_TYPES.include? @items
                 result[:items] = {:type => @items}
               else
-                result[:schema] = {'$ref' => "#/definitions/#{@items}"}
+                result[:schema] = ref_to_type(@items)
               end
             end
           else
             if PRIMITIVE_TYPES.include? @type
               result[:type] = @type
             else
-              result[:schema] = {'$ref' => "#/definitions/#{@type}"}
+              result[:schema] = ref_to_type(@type)
             end
           end
         end
@@ -80,7 +115,7 @@ module Sinatra
         if @description
           result[:description] = @description
         end
-        if @params
+        unless @params.empty?
           result.merge!(@params)
         end
 
@@ -94,11 +129,42 @@ module Sinatra
             :required => @required,
             :type => @type,
             :items => @items,
-            :params => @params,
             :description => @description,
+            :params => @params,
         }.to_json
       end
 
+      private
+
+      # Test if a parameter is a boolean
+      # @param name the parameter's name
+      # @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 a limit param like maximum and exclusiveMaximum
+      # @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(params, limit_param_name, exclusive_limit_param_name)
+        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 type #{TYPE_INTEGER} and #{TYPE_NUMBER} and not for [#{@type}]")
+          end
+        end
+
+        if params.key? exclusive_limit_param_name
+          check_boolean(PARAMS_EXCLUSIVE_MINIMUM, 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
+      end
+
     end
 
   end

data/lib/sinatra/swagger-exposer/swagger-endpoint-response.rb

@@ -26,7 +26,7 @@ module Sinatra
               if PRIMITIVE_TYPES.include? @items
                 schema[:items] = {:type => @items}
               else
-                schema[:items] = {'$ref' => "#/definitions/#{@items}"}
+                schema[:items] = ref_to_type(@items)
               end
             end
             result[:schema] = schema
@@ -34,7 +34,7 @@ module Sinatra
             if PRIMITIVE_TYPES.include? @type
               result[:schema] = {:type => @type}
             else
-              result[:schema] = {'$ref' => "#/definitions/#{@type}"}
+              result[:schema] = ref_to_type(@type)
             end
           end
         end

data/lib/sinatra/swagger-exposer/swagger-endpoint.rb

@@ -1,3 +1,4 @@
+require_relative 'swagger-request-preprocessor'
 require_relative 'swagger-utilities'
 
 module Sinatra
@@ -9,13 +10,21 @@ module Sinatra
 
       include SwaggerUtilities
 
-      attr_reader :path, :type
+      attr_reader :path, :type, :request_preprocessor
 
       def initialize(type, path, parameters, responses, summary, description, tags)
         @type = type
         @path = sinatra_path_to_swagger_path(path)
+        @request_preprocessor = SwaggerRequestPreprocessor.new
 
         @parameters = parameters
+        @parameters.each do |parameter|
+          preprocessor = parameter.preprocessor
+          if preprocessor.useful?
+            @request_preprocessor.add_preprocessor preprocessor
+          end
+        end
+
         @responses = responses
 
         @attributes = {}

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

@@ -21,13 +21,15 @@ module Sinatra
       app.set :swagger_current_endpoint_parameters, {}
       app.set :swagger_current_endpoint_responses, {}
       app.set :swagger_types, {}
+      declare_swagger_endpoints(app)
+    end
 
-      # Declare the swagger endpoints
+    def self.declare_swagger_endpoints(app)
       app.endpoint_summary 'The swagger endpoint'
       app.endpoint_tags 'swagger'
       app.get '/swagger_doc.json' do
         swagger_content = ::Sinatra::SwaggerExposer::SwaggerContentCreator.new(
-            settings.respond_to?(:swagger_info) ? settings.swagger_info : nil ,
+            settings.respond_to?(:swagger_info) ? settings.swagger_info : nil,
             settings.swagger_types,
             settings.swagger_endpoints
         ).to_swagger
@@ -40,26 +42,25 @@ module Sinatra
       app.options '/swagger_doc.json' do
         200
       end
-
     end
 
     # Provide a summary for the endpoint
     def endpoint_summary(summary)
-      set_if_type_and_not_exist(summary, 'summary', String)
+      set_if_type_and_not_exist(summary, :summary, String)
     end
 
     # Provide a description for the endpoint
     def endpoint_description(description)
-      set_if_type_and_not_exist(description, 'description', String)
+      set_if_type_and_not_exist(description, :description, String)
     end
 
     # Provide tags for the endpoint
     def endpoint_tags(*tags)
-      set_if_type_and_not_exist(tags, 'tags', nil)
+      set_if_type_and_not_exist(tags, :tags, nil)
     end
 
     # Define parameter for the endpoint
-    def endpoint_parameter(name, description, how_to_pass, required, type, params = nil)
+    def endpoint_parameter(name, description, how_to_pass, required, type, params = {})
       parameters = settings.swagger_current_endpoint_parameters
       check_if_not_duplicate(name, parameters, 'Parameter')
       parameters[name] = SwaggerEndpointParameter.new(
@@ -93,70 +94,38 @@ module Sinatra
       responses[code] = SwaggerEndpointResponse.new(type, description, settings.swagger_types.keys)
     end
 
-    def delete(*args, &block)
-      process_endpoint('delete', args)
-      super(*args, &block)
-    end
-
-    def get(*args, &block)
-      process_endpoint('get', args)
-      super(*args, &block)
-    end
-
-    def head(*args, &block)
-      process_endpoint('head', args)
-      super(*args, &block)
-    end
-
-    def link(*args, &block)
-      process_endpoint('link', args)
-      super(*args, &block)
-    end
-
-    def options(*args, &block)
-      process_endpoint('options', args)
-      super(*args, &block)
-    end
-
-    def patch(*args, &block)
-      process_endpoint('patch', args)
-      super(*args, &block)
-    end
-
-    def post(*args, &block)
-      process_endpoint('post', args)
-      super(*args, &block)
-    end
-
-    def put(*args, &block)
-      process_endpoint('put', args)
-      super(*args, &block)
-    end
-
-    def unlink(*args, &block)
-      process_endpoint('unlink', args)
-      super(*args, &block)
+    def route(verb, path, options = {}, &block)
+      if verb == 'HEAD'
+        super(verb, path, options, &block)
+      else
+        request_preprocessor = process_endpoint(verb.downcase, path, options)
+        super(verb, path, options) do
+          request_preprocessor.run(self, &block)
+        end
+      end
     end
 
     private
 
     # Call for each endpoint declaration
-    def process_endpoint(type, args)
+    # @return [SwaggerRequestPreprocessor]
+    def process_endpoint(type, path, opts)
       current_endpoint_info = settings.swagger_current_endpoint_info
       current_endpoint_parameters = settings.swagger_current_endpoint_parameters
       current_endpoint_responses = settings.swagger_current_endpoint_responses
-      endpoint_path = args[0]
-      settings.swagger_endpoints << SwaggerEndpoint.new(
+      endpoint = SwaggerEndpoint.new(
           type,
-          endpoint_path,
+          path,
           current_endpoint_parameters.values,
           current_endpoint_responses.clone,
           current_endpoint_info[:summary],
           current_endpoint_info[:description],
           current_endpoint_info[:tags])
+      settings.swagger_endpoints << endpoint
       current_endpoint_info.clear
       current_endpoint_parameters.clear
       current_endpoint_responses.clear
+      endpoint.request_preprocessor
     end
 
     def set_if_type_and_not_exist(value, name, type)

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

@@ -1,4 +1,5 @@
 require_relative 'swagger-invalid-exception'
+require_relative 'swagger-utilities'
 
 module Sinatra
 
@@ -7,6 +8,8 @@ module Sinatra
     # The info declaration
     class SwaggerInfo
 
+      include SwaggerUtilities
+
       def initialize(values)
         @values = process(values, 'info', INFO_FIELDS, values)
       end
@@ -47,7 +50,7 @@ module Sinatra
               end
             end
           else
-            raise SwaggerInvalidException.new("Unknown property [#{current_key}] for #{current_field_name}, possible keys are: #{current_fields.keys.join(', ')}: #{top_level_hash}")
+            raise SwaggerInvalidException.new("Unknown property [#{current_key}] for #{current_field_name}#{list_or_none(current_fields.keys, 'values')}")
           end
         end
         result.empty? ? nil : result

data/lib/sinatra/swagger-exposer/swagger-parameter-preprocessor.rb

@@ -0,0 +1,139 @@
+require_relative 'swagger-endpoint-parameter'
+require_relative 'swagger-invalid-exception'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    # Process the parameters for validation and enrichment
+    class SwaggerParameterPreprocessor
+
+      def initialize(name, how_to_pass, required, type, default, params)
+        @name = name.to_s
+        @how_to_pass = how_to_pass
+        @required = required
+        @type = type
+        @default = default
+        @params = params
+
+        # All headers are upcased
+        if how_to_pass == SwaggerEndpointParameter::HOW_TO_PASS_HEADER
+          @name.upcase!
+        end
+      end
+
+      def useful?
+        @required || (!@default.nil?) || [SwaggerEndpointParameter::TYPE_NUMBER, SwaggerEndpointParameter::TYPE_INTEGER, SwaggerEndpointParameter::TYPE_BOOLEAN].include?(@type)
+      end
+
+      def run(app, parsed_body)
+        case @how_to_pass
+          when SwaggerEndpointParameter::HOW_TO_PASS_QUERY, SwaggerEndpointParameter::HOW_TO_PASS_PATH
+            check_param(app.params)
+          when SwaggerEndpointParameter::HOW_TO_PASS_HEADER
+            check_param(app.headers)
+          when SwaggerEndpointParameter::HOW_TO_PASS_BODY
+            check_param(parsed_body || {})
+        end
+      end
+
+      def check_param(params)
+        if params.key?(@name)
+          params[@name] = validate_param_value(params[@name])
+        elsif @required
+          raise SwaggerInvalidException.new("Mandatory parameter [#{@name}] is missing")
+        elsif @default
+          params[@name] = @default
+        end
+        params
+      end
+
+      def validate_param_value(value)
+        case @type
+          when SwaggerEndpointParameter::TYPE_NUMBER
+            return validate_param_value_number(value)
+          when SwaggerEndpointParameter::TYPE_INTEGER
+            return validate_param_value_integer(value)
+          when SwaggerEndpointParameter::TYPE_BOOLEAN
+            return validate_param_value_boolean(value)
+        end
+      end
+
+      def validate_param_value_boolean(value)
+        if (value == 'true') || value.is_a?(TrueClass)
+          return true
+        elsif (value == 'false') || value.is_a?(FalseClass)
+          return false
+        else
+          raise SwaggerInvalidException.new("Parameter [#{@name}] should be an boolean but is [#{value}]")
+        end
+      end
+
+      def validate_param_value_integer(value)
+        begin
+          f = Float(value)
+          i = Integer(value)
+          if f == i
+            i
+          else
+            raise SwaggerInvalidException.new("Parameter [#{@name}] should be an integer but is [#{value}]")
+          end
+          value = Integer(value)
+          validate_numerical_value(value)
+          value
+        rescue ArgumentError
+          raise SwaggerInvalidException.new("Parameter [#{@name}] should be an integer but is [#{value}]")
+        rescue TypeError
+          raise SwaggerInvalidException.new("Parameter [#{@name}] should be an integer but is [#{value}]")
+        end
+      end
+
+      def validate_param_value_number(value)
+        begin
+          value = Float(value)
+          validate_numerical_value(value)
+          return value
+        rescue ArgumentError
+          raise SwaggerInvalidException.new("Parameter [#{@name}] should be a float but is [#{value}]")
+        rescue TypeError
+          raise SwaggerInvalidException.new("Parameter [#{@name}] should be a float but is [#{value}]")
+        end
+      end
+
+      # Validate a numerical value
+      # @param value [Numeric] the value
+      def validate_numerical_value(value)
+        validate_numerical_value_internal(
+            value,
+            SwaggerEndpointParameter::PARAMS_MINIMUM,
+            SwaggerEndpointParameter::PARAMS_EXCLUSIVE_MINIMUM,
+            '>=',
+            '>')
+        validate_numerical_value_internal(
+            value,
+            SwaggerEndpointParameter::PARAMS_MAXIMUM,
+            SwaggerEndpointParameter::PARAMS_EXCLUSIVE_MAXIMUM,
+            '<=',
+            '<')
+      end
+
+      # Validate the value of a number
+      # @params value the value to check
+      # @params limit_param_name [Symbol] the param that contain the value to compare to
+      # @params exclusive_limit_param_name [Symbol] the param that indicates if the comparison is absolute
+      # @params limit_param_method [String] the comparison method to call
+      # @params exclusive_limit_param_method [String] the absolute comparison method to call
+      def validate_numerical_value_internal(value, limit_param_name, exclusive_limit_param_name, limit_param_method, exclusive_limit_param_method)
+        if @params.key? limit_param_name
+          target_value = @params[limit_param_name]
+          method_to_call = @params[exclusive_limit_param_name] ? exclusive_limit_param_method : limit_param_method
+          unless value.send(method_to_call, target_value)
+            raise SwaggerInvalidException.new("Parameter [#{@name}] should be #{method_to_call} than [#{target_value}] but is [#{value}]")
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/sinatra/swagger-exposer/swagger-request-preprocessor.rb

@@ -0,0 +1,52 @@
+require 'json'
+
+require_relative 'swagger-invalid-exception'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    # A preprocessor for a request, apply the parameter preprocessor then execute the query code
+    class SwaggerRequestPreprocessor
+
+      attr_reader :preprocessors
+
+      def initialize
+        @preprocessors = []
+      end
+
+      def add_preprocessor(preprocessor)
+        @preprocessors << preprocessor
+      end
+
+      def run(app, &block)
+        parsed_body = {}
+        if app.env['CONTENT_TYPE'] == 'application/json'
+          body = app.request.body
+          unless body.empty?
+            parsed_body = JSON.parse(body)
+          end
+        end
+        app.params['parsed_body'] = parsed_body
+        unless @preprocessors.empty?
+          @preprocessors.each do |preprocessor|
+            begin
+              preprocessor.run(app, parsed_body)
+            rescue SwaggerInvalidException => e
+              app.content_type :json
+              return [400, {:code => 400, :message => e.message}.to_json]
+            end
+          end
+        end
+        if block
+          # Execute the block in the context of the app
+          app.instance_eval(&block)
+        else
+          ''
+        end
+      end
+
+    end
+
+  end
+end

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

@@ -42,7 +42,7 @@ module Sinatra
               if PRIMITIVE_TYPES.include? @items
                 result[:items] = {:type => @items}
               else
-                result[:items] = {'$ref' => "#/definitions/#{@items}"}
+                result[:items] = ref_to_type(@items)
               end
             end
           else

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

@@ -11,19 +11,27 @@ module Sinatra
 
       include SwaggerUtilities
 
-      def initialize(type_name, type_content, known_types)
-        @properties = process_properties(type_name, type_content, known_types)
-        @required = process_required(type_name, type_content, @properties.keys)
-        @example = process_example(type_name, type_content, @properties.keys)
+      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, :properties, Hash)
+        possible_value = check_attribute_empty_or_bad(type_name, type_content, PROPERTY_PROPERTIES, Hash)
         if possible_value
           possible_value
         else
           result = {}
-          type_content[:properties].each_pair do |property_name, property_properties|
+          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
@@ -31,32 +39,32 @@ module Sinatra
       end
 
       def process_required(type_name, type_content, properties_names)
-        possible_value = check_attribute_empty_or_bad(type_name, type_content, :required, Array)
+        possible_value = check_attribute_empty_or_bad(type_name, type_content, PROPERTY_REQUIRED, Array)
         if possible_value
           possible_value
         else
-          type_content[:required].each do |property_name|
+          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, known properties: #{properties_names.join(', ')}")
+              raise SwaggerInvalidException.new("Required property [#{property_name}] of [#{type_name}] is unknown#{list_or_none(properties_names, 'properties')}")
             end
           end
-          type_content[:required]
+          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, :example, Hash)
+        possible_value = check_attribute_empty_or_bad(type_name, type_content, PROPERTY_EXAMPLE, Hash)
         if possible_value
           possible_value
         else
-          type_content[:example].each_pair do |property_name, property_value|
+          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, known properties: #{properties_names.join(', ')}")
+              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[:example]
+          type_content[PROPERTY_EXAMPLE]
         end
       end
 
@@ -68,19 +76,35 @@ module Sinatra
         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 = {}
+        result = {:type => 'object'}
 
         unless @properties.empty?
-          result[:properties] = hash_to_swagger(@properties)
+          result[PROPERTY_PROPERTIES] = hash_to_swagger(@properties)
         end
 
         unless @required.empty?
-          result[:required] = @required
+          result[PROPERTY_REQUIRED] = @required
         end
 
         unless @example.empty?
-          result[:example] = @example
+          result[PROPERTY_EXAMPLE] = @example
+        end
+
+        if @extends
+          result = {
+              :allOf => [
+                ref_to_type(@extends),
+                result
+              ]
+          }
         end
 
         result

data/lib/sinatra/swagger-exposer/swagger-utilities.rb

@@ -16,9 +16,13 @@ module Sinatra
           'boolean',
           'date',
           'dateTime',
-          'password'
+          'password',
       ]
 
+      def ref_to_type(type)
+        {'$ref' => "#/definitions/#{type}"}
+      end
+
       def hash_to_swagger(hash)
         result = {}
         hash.each_pair do |key, value|
@@ -27,8 +31,12 @@ module Sinatra
         result
       end
 
+      # Transform a type into a String
+      # @return [String]
       def type_to_s(value)
-        if value.is_a? Class
+        if [TrueClass, FalseClass].include? value
+          'boolean'
+        elsif value.is_a? Class
           value.to_s.downcase
         else
           value
@@ -51,14 +59,26 @@ module Sinatra
         end
       end
 
-      def white_list_params(params, allowed_params)
+      # Validate if a parameter is in a list of available values
+      # @param params the parameter
+      # @param allowed_values [Enumerable, #include?] the allowed values
+      # @return [NilClass]
+      def white_list_params(params, allowed_values)
         params.each_pair do |key, value|
-          unless allowed_params.include? key
-            raise SwaggerInvalidException.new("Unknown property [#{key}] for with value [#{value}], known properties are #{allowed_params.join(', ')}")
+          unless allowed_values.include? key
+            raise SwaggerInvalidException.new("Unknown property [#{key}] with value [#{value}]#{list_or_none(allowed_values, 'properties')}")
           end
         end
       end
 
+      def list_or_none(list, name)
+        if list.empty?
+          ", no available #{name}"
+        else
+          ", possible #{name} are #{list.join(', ')}"
+        end
+      end
+
       private
 
       def get_array_type(array)
@@ -71,9 +91,15 @@ module Sinatra
         end
       end
 
-      def check_type(type, possible_values)
-        unless possible_values.include? type
-          raise SwaggerInvalidException.new("Unknown type [#{type}], possible types are #{possible_values.join(', ')}")
+      # Validate if a type is in a list of available values
+      # @param type [String] the parameter
+      # @param allowed_values [Enumerable, #include?] the allowed values
+      # @return [NilClass]
+      def check_type(type, allowed_values)
+        if allowed_values.empty?
+          raise SwaggerInvalidException.new("Unknown type [#{type}], no available type")
+        elsif !allowed_values.include?(type)
+          raise SwaggerInvalidException.new("Unknown type [#{type}]#{list_or_none(allowed_values, 'types')}")
         end
       end
 

data/lib/sinatra/swagger-exposer/version.rb

@@ -1,5 +1,5 @@
 module Sinatra
   module SwaggerExposer
-    VERSION = '0.0.1'
+    VERSION = '0.1.0'
   end
 end

data/sinatra-swagger-exposer.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Julien Kirch']
 
   spec.summary       = %q{Expose swagger API from your Sinatra app}
-  spec.description   = %q{This Sinatra extension enable you to add metadata to your code and to expose your API as a Swagger endpoint}
+  spec.description   = %q{This Sinatra extension enable you to add metadata to your code to expose your API as a Swagger endpoint and to validate and enrich the invocation parameters}
   spec.homepage      = 'https://github.com/archiloque/sinatra-swagger-exposer'
   spec.license       = 'MIT'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-swagger-exposer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Julien Kirch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-05 00:00:00.000000000 Z
+date: 2015-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -94,8 +94,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: This Sinatra extension enable you to add metadata to your code and to
-  expose your API as a Swagger endpoint
+description: This Sinatra extension enable you to add metadata to your code to expose
+  your API as a Swagger endpoint and to validate and enrich the invocation parameters
 email: 
 executables: []
 extensions: []
@@ -103,10 +103,11 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
-- README.asciidoc
+- README.md
 - Rakefile
 - example/Gemfile
 - example/Gemfile.lock
@@ -119,6 +120,8 @@ files:
 - lib/sinatra/swagger-exposer/swagger-exposer.rb
 - lib/sinatra/swagger-exposer/swagger-info.rb
 - lib/sinatra/swagger-exposer/swagger-invalid-exception.rb
+- lib/sinatra/swagger-exposer/swagger-parameter-preprocessor.rb
+- lib/sinatra/swagger-exposer/swagger-request-preprocessor.rb
 - lib/sinatra/swagger-exposer/swagger-type-property.rb
 - lib/sinatra/swagger-exposer/swagger-type.rb
 - lib/sinatra/swagger-exposer/swagger-utilities.rb

data/README.asciidoc

@@ -1,75 +0,0 @@
-# Sinatra::SwaggerExposer
-
-image:https://codeclimate.com/github/archiloque/sinatra-swagger-exposer/badges/gpa.svg["Code status", link=https://codeclimate.com/github/archiloque/sinatra-swagger-exposer]
-image:https://travis-ci.org/archiloque/sinatra-swagger-exposer.svg?branch=master["Build Status", link="https://travis-ci.org/archiloque/sinatra-swagger-exposer"]
-image:https://coveralls.io/repos/archiloque/sinatra-swagger-exposer/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/r/archiloque/sinatra-swagger-exposer?branch=master"]
-
-Create Swagger endpoint for your Sinatra application.
-
-This Sinatra extension enable you to add metadata to your code and to expose your API as a Swagger endpoint.
-
-I'm adding features as I need them and it currently doesn't use all the Swagger options, so if you need one that is missing please open an issue or contribute.
-
-## Design choices
-
-- All the declarations are validated when the server is started
-- The declarations are defined to look as ruby-ish as possible
-
-To use it in your app :
-
-[source,ruby]
-----
-require 'sinatra/swagger-exposer/swagger-exposer'
-
-class MyApp < Sinatra::Base
-
-  register Sinatra::SwaggerExposer
-
-  general_info(
-      {
-          version: '0.0.1',
-          title: 'May app',
-          description: 'My wonderful app',
-          license: {
-              name: 'MIT',
-              url: 'http://opensource.org/licenses/MIT'
-          }
-      }
-  )
-
-  type 'Status',
-               {
-                   :properties => {
-                       :status => {
-                           :type => String,
-                           :example => 'OK,
-                       },
-                   },
-                   :required => [:status]
-               }
-
-  endpoint_description 'Base method to ping'
-  endpoint_response 200, 'Standard response', 'Status'
-  endpoint_tags 'Ping'
-  get '/' do
-    json({'status' => 'OK'})
-  end
-
-end
-----
-
-The swagger json endpoint will be exposed at `/swagger_doc.json`.
-
-## Detailed example
-
-A more complete example is available link:https://github.com/archiloque/sinatra-swagger-exposer/tree/master/example[here].
-
-## Resources
-
-- link:https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md[Swagger RESTful API Documentation Specification].
-- link:https://github.com/swagger-api/swagger-spec/tree/master/examples/v2.0/json[Swagger json examples].
-- link:https://raw.githubusercontent.com/swagger-api/swagger-spec/master/schemas/v2.0/schema.json[The swagger json schema].
-
-## License
-
-This software is released under the MIT license.