sinatra-swagger-exposer-ng 0.5.0

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

@@ -0,0 +1,258 @@
+require 'sinatra/base'
+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-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
+
+      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
+
+    # 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.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
+        ).to_swagger
+        content_type :json
+        swagger_content.to_json
+      end
+
+      app.endpoint_summary 'Option method for the swagger endpoint, useful for some CORS stuff'
+      app.endpoint_tags 'swagger'
+      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
+
+    # Define parameter for the endpoint
+    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] = Sinatra::SwaggerExposer::Configuration::SwaggerEndpointParameter.new(
+        name,
+        description,
+        how_to_pass,
+        required,
+        type,
+        params,
+        settings.swagger_types.types_names)
+    end
+
+    # Define fluent endpoint dispatcher
+    # @param params [Hash] the parameters
+    def endpoint(params)
+      params.each_pair do |param_name, param_value|
+        case param_name
+          when :summary
+            endpoint_summary param_value
+          when :description
+            endpoint_description param_value
+          when :tags
+            endpoint_tags *param_value
+          when :produces
+            endpoint_produces *param_value
+          when :path
+            endpoint_path param_value
+          when :parameters
+            param_value.each do |param, args_param|
+              endpoint_parameter param, *args_param
+            end
+          when :responses
+            param_value.each do |code, args_response|
+              endpoint_response code, *args_response
+            end
+          else
+            raise SwaggerInvalidException.new("Invalid endpoint parameter [#{param_name}]")
+        end
+      end
+    end
+
+    # General information
+    def general_info(params)
+      set :swagger_info, Sinatra::SwaggerExposer::Configuration::SwaggerInfo.new(params)
+    end
+
+    # Declare a type
+    def type(name, params)
+      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
+    # @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,
+        headers,
+        settings.swagger_response_headers
+      )
+    end
+
+    # Override Sinatra route method
+    def route(verb, path, options = {}, &block)
+      no_swagger = options[:no_swagger]
+      options.delete(:no_swagger)
+      if (verb == 'HEAD') || no_swagger
+        super(verb, path, options, &block)
+      else
+        request_processor = create_request_processor(verb.downcase, path, options)
+        super(verb, path, options) do |*params|
+          response = catch(:halt) do
+            request_processor.run(self, params, &block)
+          end
+          if settings.result_validation
+            begin
+              # Inspired from Sinatra#invoke
+              if (Integer === response) or (String === response)
+                response = [response]
+              end
+              if (Array === response) and (Integer === 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
+
+    private
+
+    # Call for each endpoint declaration
+    # @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])
+      settings.swagger_endpoints << endpoint
+      current_endpoint_info.clear
+      current_endpoint_parameters.clear
+      current_endpoint_responses.clear
+      settings.swagger_processor_creator.create_request_processor(endpoint)
+    end
+
+    def set_if_not_exist(value, name)
+      if settings.swagger_current_endpoint_info.key? name
+        raise SwaggerInvalidException.new("#{name} with value [#{value}] already defined: [#{settings.swagger_current_endpoint_info[name]}]")
+      end
+      settings.swagger_current_endpoint_info[name] = value
+    end
+
+    def set_if_type_and_not_exist(value, name, type)
+      unless value.is_a? type
+        raise SwaggerInvalidException.new("#{name} [#{value}] should be a #{type.to_s.downcase}")
+      end
+      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]}]")
+      end
+    end
+
+  end
+
+end

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

@@ -0,0 +1,16 @@
+module Sinatra
+
+  module SwaggerExposer
+
+    # When something is wrong
+    class SwaggerInvalidException < Exception
+
+      def initialize(message)
+        super(message)
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,73 @@
+module Sinatra
+
+  module SwaggerExposer
+
+    # Helper for handling the parameters
+    module SwaggerParameterHelper
+
+      HOW_TO_PASS_BODY = 'body'
+      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_BOOLEAN = 'boolean'
+      TYPE_BYTE = 'byte'
+      TYPE_DATE = 'date'
+      TYPE_DOUBLE = 'double'
+      TYPE_DATE_TIME = 'dateTime'
+      TYPE_FLOAT = 'float'
+      TYPE_INTEGER = 'integer'
+      TYPE_LONG = 'long'
+      TYPE_NUMBER = 'number'
+      TYPE_PASSWORD = 'password'
+      TYPE_STRING = 'string'
+      TYPE_ARRAY = 'array'
+
+      PRIMITIVE_TYPES = [
+        TYPE_INTEGER,
+        TYPE_LONG,
+        TYPE_FLOAT,
+        TYPE_DOUBLE,
+        TYPE_STRING,
+        TYPE_BYTE,
+        TYPE_BOOLEAN,
+        TYPE_DATE,
+        TYPE_DATE_TIME,
+        TYPE_PASSWORD,
+      ]
+
+      TYPE_FILE = 'file'
+
+      PRIMITIVE_TYPES_FOR_NON_BODY = [TYPE_STRING, TYPE_NUMBER, TYPE_INTEGER, TYPE_BOOLEAN]
+
+      PARAMS_FORMAT = :format
+      PARAMS_DEFAULT = :default
+      PARAMS_EXAMPLE = :example
+
+      # For numbers
+      PARAMS_MINIMUM = :minimum
+      PARAMS_MAXIMUM = :maximum
+      PARAMS_EXCLUSIVE_MINIMUM = :exclusiveMinimum
+      PARAMS_EXCLUSIVE_MAXIMUM = :exclusiveMaximum
+
+      # For strings
+      PARAMS_MIN_LENGTH = :minLength
+      PARAMS_MAX_LENGTH = :maxLength
+
+      PARAMS_LIST = [
+        PARAMS_FORMAT,
+        PARAMS_DEFAULT,
+        PARAMS_EXAMPLE,
+        PARAMS_MINIMUM,
+        PARAMS_MAXIMUM,
+        PARAMS_EXCLUSIVE_MINIMUM,
+        PARAMS_EXCLUSIVE_MAXIMUM,
+        PARAMS_MIN_LENGTH,
+        PARAMS_MAX_LENGTH,
+      ]
+
+    end
+
+  end
+end

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

@@ -0,0 +1,188 @@
+require_relative 'swagger-parameter-helper'
+
+require_relative 'processing/swagger-array-value-processor'
+require_relative 'processing/swagger-file-processor-dispatcher'
+require_relative 'processing/swagger-processor-dispatcher'
+require_relative 'processing/swagger-primitive-value-processor'
+require_relative 'processing/swagger-request-processor'
+require_relative 'processing/swagger-response-processor'
+require_relative 'processing/swagger-type-value-processor'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    # Create processor from configuration
+    class SwaggerProcessorCreator
+
+      include Sinatra::SwaggerExposer::SwaggerParameterHelper
+
+      # Initialize
+      # @param types [Sinatra::SwaggerExposer::SwaggerTypes]
+      def initialize(types)
+        @types = types
+      end
+
+      # Create an endpoint processor
+      # @param swagger_endpoint [Sinatra::SwaggerExposer::Configuration::SwaggerEndpoint] the endpoint
+      # @return [Sinatra::SwaggerExposer::Processing::SwaggerRequestProcessor]
+      def create_request_processor(swagger_endpoint)
+        request_processor = Sinatra::SwaggerExposer::Processing::SwaggerRequestProcessor.new(swagger_endpoint.produces)
+
+        swagger_endpoint.parameters.each do |parameter|
+          if TYPE_FILE == parameter.type
+            dispatcher = Sinatra::SwaggerExposer::Processing::SwaggerFileProcessorDispatcher.new(
+              parameter.name,
+              parameter.required
+            )
+          else
+            processor = create_parameter_value_processor(parameter)
+            dispatcher = Sinatra::SwaggerExposer::Processing::SwaggerProcessorDispatcher.new(
+              parameter.how_to_pass,
+              processor
+            )
+          end
+          if dispatcher.useful?
+            request_processor.add_dispatcher(dispatcher)
+          end
+        end
+
+        swagger_endpoint.responses.each_pair do |code, endpoint_response|
+          response_value_processor = create_response_value_processor(endpoint_response)
+          response_processor = Sinatra::SwaggerExposer::Processing::SwaggerResponseProcessor.new(
+            endpoint_response,
+            response_value_processor
+          )
+          request_processor.add_response_processor(
+            code,
+            response_processor.useful? ? response_processor : nil
+          )
+        end
+
+        request_processor
+      end
+
+      private
+
+      # Create a response processor
+      # @param endpoint_response [Sinatra::SwaggerExposer::Configuration::SwaggerEndpointResponse]
+      # @return [Sinatra::SwaggerExposer::Processing::SwaggerTypeValueProcessor]
+      def create_response_value_processor(endpoint_response)
+        response_type = endpoint_response.type
+        if response_type == TYPE_ARRAY
+          processor_for_values = create_processor_for_type('Response', endpoint_response.items, false)
+          Sinatra::SwaggerExposer::Processing::SwaggerArrayValueProcessor.new('Response', true, processor_for_values)
+        elsif response_type == TYPE_FILE
+          # Don't validate the files' content
+          nil
+        elsif response_type
+          create_processor_for_type('Response', response_type, false)
+        else
+          nil
+        end
+      end
+
+      # Create a parameter processor for a parameter
+      # @param parameter [Sinatra::SwaggerExposer::Configuration::SwaggerEndpointParameter]
+      # @return [Sinatra::SwaggerExposer::Processing::SwaggerTypeValueProcessor]
+      def create_parameter_value_processor(parameter)
+        type_name = parameter.type
+        if type_name == TYPE_ARRAY
+          if PRIMITIVE_TYPES.include? parameter.items
+            processor_for_values = Sinatra::SwaggerExposer::Processing::SwaggerPrimitiveValueProcessor.new(
+              parameter.name,
+              false,
+              parameter.items,
+              parameter.default,
+              parameter.params
+            )
+          else
+            processor_for_values = create_processor_for_type(parameter.name, parameter.items, false)
+          end
+          Sinatra::SwaggerExposer::Processing::SwaggerArrayValueProcessor.new(
+            parameter.name,
+            parameter.required,
+            processor_for_values
+          )
+        elsif PRIMITIVE_TYPES.include? type_name
+          Sinatra::SwaggerExposer::Processing::SwaggerPrimitiveValueProcessor.new(
+            parameter.name,
+            parameter.required,
+            type_name,
+            parameter.default,
+            parameter.params
+          )
+        else
+          create_processor_for_type(parameter.name, parameter.type, parameter.required)
+        end
+      end
+
+      # Create a type parameter processor for a type parameter
+      # @param parameter_name [String] the parameter name
+      # @param parameter_type [String] the parameter type
+      # @param parameter_required [TrueClass] if the parameter is required
+      # @return [Sinatra::SwaggerExposer::Processing::SwaggerTypeValueProcessor]
+      def create_processor_for_type(parameter_name, parameter_type, parameter_required)
+        attributes_processors = create_attributes_processors_for_type(parameter_type)
+        Sinatra::SwaggerExposer::Processing::SwaggerTypeValueProcessor.new(
+          parameter_name,
+          parameter_required,
+          attributes_processors
+        )
+      end
+
+      # Get attributes processor for a type
+      # @param type_name [String] the type name
+      # @return [Array<Sinatra::SwaggerExposer::Processing::SwaggerBaseValueProcessor>]
+      def create_attributes_processors_for_type(type_name)
+        type = @types[type_name]
+        attributes_processors = []
+        type.properties.each_pair do |property_name, property|
+          attributes_processors <<
+            create_processor_for_property(
+              property_name,
+              property,
+              type.required.include?(property.name)
+            )
+        end
+        if type.extends
+          attributes_processors = attributes_processors + create_attributes_processors_for_type(type.extends)
+        end
+        attributes_processors
+      end
+
+      # Create a processor for a type property
+      # @param type_property [Sinatra::SwaggerExposer::Configuration::SwaggerTypeProperty]
+      # @return [Sinatra::SwaggerExposer::Processing::SwaggerBaseValueProcessor]
+      def create_processor_for_property(name, type_property, required)
+        property_type = type_property.type
+        if property_type == TYPE_ARRAY
+          if PRIMITIVE_TYPES.include? type_property.items
+            processor_for_values = Sinatra::SwaggerExposer::Processing::SwaggerPrimitiveValueProcessor.new(
+              name,
+              false,
+              type_property.items,
+              type_property.properties[:default],
+              type_property.properties
+            )
+          else
+            processor_for_values = create_processor_for_type(name, type_property.items, false)
+          end
+          Sinatra::SwaggerExposer::Processing::SwaggerArrayValueProcessor.new(name, required, processor_for_values)
+        elsif PRIMITIVE_TYPES.include? property_type
+          Sinatra::SwaggerExposer::Processing::SwaggerPrimitiveValueProcessor.new(
+            name,
+            required,
+            property_type,
+            type_property.properties[:default],
+            type_property.properties
+          )
+        else
+          create_processor_for_type(name, property_type, required)
+        end
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,5 @@
+module Sinatra
+  module SwaggerExposer
+    VERSION = '0.5.0'
+  end
+end

data/sinatra-swagger-exposer.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sinatra/swagger-exposer/version'
+
+excluded_patterns = ['test/', 'example/', '.travis.yml', '.gitignore']
+
+Gem::Specification.new do |spec|
+  spec.name = 'sinatra-swagger-exposer-ng'
+  spec.version = Sinatra::SwaggerExposer::VERSION
+  spec.authors = ['Julien Kirch', 'Camille Paquet']
+
+  spec.summary = %q{Expose swagger API from your Sinatra app}
+  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. Fork from Julien Kirch.}
+  spec.homepage = 'https://github.com/ultragreen/sinatra-swagger-exposer'
+  spec.license = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| excluded_patterns.any? { |ep| f.start_with?(ep) } }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'sinatra', '~> 2.1'
+  spec.add_dependency 'mime-types', '~> 3.4'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'minitest', '~> 5.14'
+  spec.add_development_dependency 'rack-test', '~> 1.1'
+  spec.add_development_dependency 'simplecov'
+
+end