sinatra-swagger-exposer 0.3.0 → 0.4.0

data/lib/sinatra/swagger-exposer/processing/{swagger-preprocessor-dispatcher.rb → swagger-processor-dispatcher.rb}

@@ -6,23 +6,23 @@ module Sinatra
 
     module Processing
 
-      # Dispatch content to a preprocessor
-      class SwaggerPreprocessorDispatcher
+      # Dispatch content to a processor
+      class SwaggerProcessorDispatcher
 
-        attr_reader :how_to_pass, :preprocessor
+        attr_reader :how_to_pass, :processor
 
         include Sinatra::SwaggerExposer::SwaggerParameterHelper
 
         # Initialize
-        # @param how_to_pass how the value should be passed to the preprocessor
-        # @param preprocessor [Sinatra::SwaggerExposer::Processing::SwaggerBaseValuePreprocessor] processor for the values
-        def initialize(how_to_pass, preprocessor)
+        # @param how_to_pass how the value should be passed to the processor
+        # @param processor [Sinatra::SwaggerExposer::Processing::SwaggerBaseValueProcessor] processor for the values
+        def initialize(how_to_pass, processor)
           @how_to_pass = how_to_pass
-          @preprocessor = preprocessor
+          @processor = processor
         end
 
         def useful?
-          (@how_to_pass != HOW_TO_PASS_PATH) && @preprocessor.useful?
+          (@how_to_pass != HOW_TO_PASS_PATH) && @processor.useful?
         end
 
         # Process the value
@@ -31,11 +31,11 @@ module Sinatra
             when HOW_TO_PASS_PATH
               # can't validate
             when HOW_TO_PASS_QUERY
-              @preprocessor.process(app.params)
+              @processor.process(app.params)
             when HOW_TO_PASS_HEADER
-              @preprocessor.process(app.headers)
+              @processor.process(app.headers)
             when HOW_TO_PASS_BODY
-              @preprocessor.process(parsed_body || {})
+              @processor.process(parsed_body || {})
           end
         end
 

data/lib/sinatra/swagger-exposer/processing/swagger-request-processor.rb

@@ -0,0 +1,123 @@
+require 'json'
+require 'mime-types'
+
+require_relative '../swagger-invalid-exception'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Processing
+
+      # Custom mime types that matches everything when '*' is in list
+      class AllMimesTypes
+
+        def like?(other)
+          true
+        end
+
+      end
+
+      # A processor for a request, apply the parameters processors then execute the query code
+      class SwaggerRequestProcessor
+
+        attr_reader :processors_dispatchers, :response_processors, :produces
+
+        # @param produces [Array<String>]
+        def initialize(produces = nil)
+          @processors_dispatchers = []
+          @response_processors = {}
+          @produces = produces
+          if produces
+            @produces_types = produces.collect do |produce|
+              if produce == '*'
+                [Sinatra::SwaggerExposer::Processing::AllMimesTypes.new]
+              else
+                MIME::Types[produce]
+              end
+            end.flatten
+          end
+        end
+
+        # @param dispatcher [Sinatra::SwaggerExposer::Processing::SwaggerProcessorDispatcher]
+        def add_dispatcher(dispatcher)
+          @processors_dispatchers << dispatcher
+        end
+
+        # @param response_processor [Sinatra::SwaggerExposer::Processing::SwaggerResponseProcessor]
+        def add_response_processor(code, response_processor)
+          @response_processors[code] = response_processor
+        end
+
+        JSON_CONTENT_TYPE = MIME::Types['application/json'].first
+
+        # Run the processor the call the route content
+        # @param app the sinatra app being run
+        # @param block_params [Array] the block parameters
+        # @param block the block containing the route content
+        def run(app, block_params, &block)
+          parsed_body = {}
+          if JSON_CONTENT_TYPE.like?(app.env['CONTENT_TYPE'])
+            body = app.request.body.read
+            unless body.empty?
+              begin
+                parsed_body = JSON.parse(body)
+              rescue JSON::ParserError => e
+                return [400, {:code => 400, :message => e.message}.to_json]
+              end
+            end
+          end
+          app.params['parsed_body'] = parsed_body
+          unless @processors_dispatchers.empty?
+            @processors_dispatchers.each do |processor_dispatcher|
+              begin
+                processor_dispatcher.process(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_exec(*block_params, &block)
+          else
+            ''
+          end
+        end
+
+        # Validate the response
+        # @param response_body [String] the body
+        # @param content_type [String] the content type
+        # @param response_status [Integer] the status
+        def validate_response(response_body, content_type, response_status)
+          validate_response_content_type(content_type, response_status)
+          if @response_processors.key?(response_status)
+            response_processor = response_processors[response_status]
+            if JSON_CONTENT_TYPE.like?(content_type) && response_processor
+              response_processor.validate_response(response_body)
+            end
+          else
+            raise SwaggerInvalidException.new("Status with unknown response status [#{response_status}], known statuses are [#{@response_processors.keys.join(', ')}] response value is #{response_body}")
+          end
+        end
+
+        # Validate a response content type
+        # @param content_type [String] the content type to validate
+        # @param response_status [Integer] the status
+        def validate_response_content_type(content_type, response_status)
+          if content_type.nil? && (response_status == 204)
+            # No content and no content type => everything is OK
+          elsif @produces
+            unless @produces_types.any? { |produce| produce.like?(content_type) }
+              raise SwaggerInvalidException.new("Undeclared content type [#{content_type}], declared content type are [#{@produces.join(', ')}]")
+            end
+          elsif !JSON_CONTENT_TYPE.like?(content_type)
+            raise SwaggerInvalidException.new("Undeclared content type [#{content_type}], if no declaration for the endpoint you should only return json")
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/sinatra/swagger-exposer/processing/swagger-response-processor.rb

@@ -0,0 +1,47 @@
+require_relative '../swagger-parameter-helper'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Processing
+
+      # Process a response
+      class SwaggerResponseProcessor
+
+        include Sinatra::SwaggerExposer::SwaggerParameterHelper
+
+        attr_reader :endpoint_response, :processor
+
+        # Initialize
+        # @param endpoint_response [Sinatra::SwaggerExposer::Configuration::SwaggerEndpointResponse]
+        # @param processor [Sinatra::SwaggerExposer::Processing::SwaggerTypeValueProcessor]
+        def initialize(endpoint_response, processor)
+          @endpoint_response = endpoint_response
+          @processor = processor
+        end
+
+        # Test if the processor is useful
+        # @return [TrueClass]
+        def useful?
+          (@endpoint_response && (@endpoint_response.type != TYPE_FILE)) || @processor
+        end
+
+        # Validate a response
+        # @param response_body [String] the body
+        def validate_response(response_body)
+          parsed_response_body = nil
+          begin
+            parsed_response_body = JSON.parse(response_body)
+          rescue JSON::ParserError => e
+            raise SwaggerInvalidException.new("Response is not a valid json [#{response_body}]")
+          end
+          if @processor
+            @processor.validate_value(parsed_response_body)
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+require_relative 'swagger-base-value-processor'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Processing
+
+      # A processor for a type parameter
+      class SwaggerTypeValueProcessor < SwaggerBaseValueProcessor
+
+        attr_reader :attributes_processors
+
+        # Initialize
+        # @param name [String] the name
+        # @param required [TrueClass] if the parameter is required
+        # @param attributes_processors [Array<Sinatra::SwaggerExposer::Processing::SwaggerBaseValueProcessor>] the attributes processors
+        def initialize(name, required, attributes_processors)
+          super(name, required, nil)
+          @attributes_processors = attributes_processors
+        end
+
+        def useful?
+          super || (!(@attributes_processors.empty?))
+        end
+
+        def validate_value(value)
+          @attributes_processors.each do |attribute_processor|
+            attribute_processor.process(value)
+          end
+          value
+        end
+
+      end
+    end
+  end
+end

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

@@ -1,5 +1,3 @@
-require_relative 'swagger-utilities'
-
 module Sinatra
 
   module SwaggerExposer
@@ -7,8 +5,6 @@ module Sinatra
     # Create the swagger content
     class SwaggerContentCreator
 
-      include SwaggerUtilities
-
       def initialize(swagger_info, swagger_types, swagger_endpoints)
         @swagger_info = swagger_info
         @swagger_types = swagger_types
@@ -17,9 +13,9 @@ module Sinatra
 
       def to_swagger
         result = {
-            swagger: '2.0',
-            consumes: ['application/json'],
-            produces: ['application/json'],
+          swagger: '2.0',
+          consumes: ['application/json'],
+          produces: ['application/json'],
         }
         if @swagger_info
           result[:info] = @swagger_info.to_swagger

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

@@ -4,36 +4,48 @@ require 'json'
 require_relative 'configuration/swagger-endpoint'
 require_relative 'configuration/swagger-endpoint-parameter'
 require_relative 'configuration/swagger-endpoint-response'
+require_relative 'configuration/swagger-response-headers'
 require_relative 'configuration/swagger-info'
 require_relative 'configuration/swagger-types'
 require_relative 'swagger-content-creator'
 require_relative 'swagger-invalid-exception'
-require_relative 'swagger-preprocessor-creator'
+require_relative 'swagger-request-processor-creator'
 
 module Sinatra
 
   # Expose swagger API from your Sinatra app
   module SwaggerExposer
 
+    # Called when we register the extension
+    # @param app [Sinatra::Base]
     def self.registered(app)
+      app.set :result_validation, (ENV['RACK_ENV'] != 'production')
       app.set :swagger_endpoints, []
       app.set :swagger_current_endpoint_info, {}
       app.set :swagger_current_endpoint_parameters, {}
       app.set :swagger_current_endpoint_responses, {}
+
       swagger_types = Sinatra::SwaggerExposer::Configuration::SwaggerTypes.new
       app.set :swagger_types, swagger_types
-      app.set :swagger_preprocessor_creator, Sinatra::SwaggerExposer::SwaggerPreprocessorCreator.new(swagger_types)
-      declare_swagger_endpoints(app)
+
+      response_headers = Sinatra::SwaggerExposer::Configuration::SwaggerResponseHeaders.new
+      app.set :swagger_response_headers, response_headers
+
+      app.set :swagger_processor_creator, Sinatra::SwaggerExposer::SwaggerProcessorCreator.new(swagger_types)
+      declare_swagger_endpoint(app)
     end
 
-    def self.declare_swagger_endpoints(app)
+    # Declare the endpoint to serve the swagger content
+    # @param app [Sinatra::Base]
+    def self.declare_swagger_endpoint(app)
       app.endpoint_summary 'The swagger endpoint'
       app.endpoint_tags 'swagger'
-      app.get '/swagger_doc.json' do
+      app.endpoint_response 200
+      app.get('/swagger_doc.json') do
         swagger_content = Sinatra::SwaggerExposer::SwaggerContentCreator.new(
-            settings.respond_to?(:swagger_info) ? settings.swagger_info : nil,
-            settings.swagger_types,
-            settings.swagger_endpoints
+          settings.respond_to?(:swagger_info) ? settings.swagger_info : nil,
+          settings.swagger_types,
+          settings.swagger_endpoints
         ).to_swagger
         content_type :json
         swagger_content.to_json
@@ -41,32 +53,40 @@ module Sinatra
 
       app.endpoint_summary 'Option method for the swagger endpoint, useful for some CORS stuff'
       app.endpoint_tags 'swagger'
-      app.options '/swagger_doc.json' do
+      app.endpoint_response 200
+      app.endpoint_produces 'text/plain;charset=utf-8'
+      app.options('/swagger_doc.json') do
+        content_type :text
         200
       end
     end
 
     # Provide a summary for the endpoint
+    # @param summary [String]
     def endpoint_summary(summary)
       set_if_type_and_not_exist(summary, :summary, String)
     end
 
     # Provide a path
+    # @param path [String]
     def endpoint_path(path)
       set_if_type_and_not_exist(path, :path, String)
     end
 
     # Provide a description for the endpoint
+    # @param description [String]
     def endpoint_description(description)
       set_if_type_and_not_exist(description, :description, String)
     end
 
     # Provide tags for the endpoint
+    # @param tags [Array<String>]
     def endpoint_tags(*tags)
       set_if_not_exist(tags, :tags)
     end
 
     # Provide produces params for the endpoint
+    # @param produces [Array<String>] the response types
     def endpoint_produces(*produces)
       set_if_not_exist(produces, :produces)
     end
@@ -76,13 +96,13 @@ module Sinatra
       parameters = settings.swagger_current_endpoint_parameters
       check_if_not_duplicate(name, parameters, 'Parameter')
       parameters[name] = Sinatra::SwaggerExposer::Configuration::SwaggerEndpointParameter.new(
-          name,
-          description,
-          how_to_pass,
-          required,
-          type,
-          params,
-          settings.swagger_types.types_names)
+        name,
+        description,
+        how_to_pass,
+        required,
+        type,
+        params,
+        settings.swagger_types.types_names)
     end
 
     # Define fluent endpoint dispatcher
@@ -124,20 +144,62 @@ module Sinatra
       settings.swagger_types.add_type(name, params)
     end
 
+    # Declare a response header
+    def response_header(name, type, description)
+      settings.swagger_response_headers.add_response_header(name, type, description)
+    end
+
     # Declare a response
-    def endpoint_response(code, type = nil, description = nil)
+    # @param code [Integer] the response code
+    # @param type the type
+    # @param description [String] the description
+    # @param headers [Array<String>] the headers names
+    def endpoint_response(code, type = nil, description = nil, headers = [])
       responses = settings.swagger_current_endpoint_responses
       check_if_not_duplicate(code, responses, 'Response')
-      responses[code] = Sinatra::SwaggerExposer::Configuration::SwaggerEndpointResponse.new(type, description, settings.swagger_types.types_names)
+      responses[code] = Sinatra::SwaggerExposer::Configuration::SwaggerEndpointResponse.new(
+        type,
+        description,
+        settings.swagger_types.types_names,
+        headers,
+        settings.swagger_response_headers
+      )
     end
 
+    # Override Sinatra route method
     def route(verb, path, options = {}, &block)
-      if verb == 'HEAD'
+      no_swagger = options[:no_swagger]
+      options.delete(:no_swagger)
+      if (verb == 'HEAD') || no_swagger
         super(verb, path, options, &block)
       else
-        request_preprocessor = process_endpoint(verb.downcase, path, options)
+        request_processor = create_request_processor(verb.downcase, path, options)
         super(verb, path, options) do |*params|
-          request_preprocessor.run(self, params, &block)
+          response = catch(:halt) do
+            request_processor.run(self, params, &block)
+          end
+          if settings.result_validation
+            begin
+              # Inspired from Sinatra#invoke
+              if (Fixnum === response) or (String === response)
+                response = [response]
+              end
+              if (Array === response) and (Fixnum === response.first)
+                response_for_validation = response.dup
+                response_status = response_for_validation.shift
+                response_body = response_for_validation.pop
+                response_headers = (response_for_validation.pop || {}).merge(self.response.header)
+                response_content_type = response_headers['Content-Type']
+                request_processor.validate_response(response_body, response_content_type, response_status)
+              elsif response.respond_to? :each
+                request_processor.validate_response(response.first.dup, self.response.header['Content-Type'], 200)
+              end
+            rescue Sinatra::SwaggerExposer::SwaggerInvalidException => e
+              content_type :json
+              throw :halt, [400, {:code => 400, :message => e.message}.to_json]
+            end
+          end
+          throw :halt, response
         end
       end
     end
@@ -145,26 +207,26 @@ module Sinatra
     private
 
     # Call for each endpoint declaration
-    # @return [SwaggerRequestPreprocessor]
-    def process_endpoint(type, path, opts)
+    # @return [Sinatra::SwaggerExposer::Processing::SwaggerRequestProcessor]
+    def create_request_processor(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 = Sinatra::SwaggerExposer::Configuration::SwaggerEndpoint.new(
-          type,
-          path,
-          current_endpoint_parameters.values,
-          current_endpoint_responses.clone,
-          current_endpoint_info[:summary],
-          current_endpoint_info[:description],
-          current_endpoint_info[:tags],
-          current_endpoint_info[:path],
-          current_endpoint_info[:produces])
+        type,
+        path,
+        current_endpoint_parameters.values,
+        current_endpoint_responses.clone,
+        current_endpoint_info[:summary],
+        current_endpoint_info[:description],
+        current_endpoint_info[:tags],
+        current_endpoint_info[:path],
+        current_endpoint_info[:produces])
       settings.swagger_endpoints << endpoint
       current_endpoint_info.clear
       current_endpoint_parameters.clear
       current_endpoint_responses.clear
-      settings.swagger_preprocessor_creator.create_endpoint_processor(endpoint)
+      settings.swagger_processor_creator.create_request_processor(endpoint)
     end
 
     def set_if_not_exist(value, name)
@@ -181,6 +243,10 @@ module Sinatra
       set_if_not_exist(value, name)
     end
 
+    # Check if a value does not exist in a hash and throw an Exception
+    # @param key the key to validate
+    # @param values [Hash] the existing keys
+    # @param name [String] the valud name for the error message
     def check_if_not_duplicate(key, values, name)
       if values.key? key
         raise SwaggerInvalidException.new("#{name} already exist for #{key} with value [#{values[key]}]")