sinatra-swagger-exposer 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5aed90279990c755b73bdd72cada6ffa5437050f
-  data.tar.gz: b11db6f75e29d6bce33a8f158e960754a2f94289
+  metadata.gz: 99783f615757c81a5f32093c96bc4e6c8daca8ca
+  data.tar.gz: 48bfb098f71405d8d75c800dba55108fa453db29
 SHA512:
-  metadata.gz: 79b57a8f5ddeb0c8d7cc8503550f5393274eec14527a1d5c23c5e123e8b6320a97b952b0945a0107e77ba143f82caaac4aa7c5106e5e39368c5d098872c1407d
-  data.tar.gz: 1a2fe99a4e7c6fd264023c952dfab82abd07f2a58f6009e1c933aa9179cf980c38f5997f860ed76d5265397a4bbf814eeede16ddff87fbabcb4a2ffb575a6e07
+  metadata.gz: ef40b1896dc2f5f12ba702620d469868698b427d29d4600014a5804eb1dca682aa197e0f14287fde1d9f2b962dce7acfd3ef5b0b6596b0a46c35f2a5147bd37d
+  data.tar.gz: a5a48f8e4a46fece4af4a015fe87e77c9ca12bedc4822f32a306247c323dfe9a4c0f3e6491fb755058fcf741cfe89d876c3741699cafcaa093570b918285c848

data/CHANGELOG.md

@@ -1,4 +1,11 @@
+# 0.4.0
+
+- Validate responses
+- No validation when the parameter is null
+- Accept :no_swagger param in declaration
+
 # 0.3.0
+
 - Can now accept types as parameters
 - Accept json utf-8 content type
 

data/Gemfile

@@ -1,6 +1,5 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in sinatra-swagger-exposer.gemspec
 gemspec
 
 gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -10,6 +10,7 @@ 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
+- validate the responses during test dans development
 
 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.
 

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

@@ -0,0 +1,124 @@
+require_relative '../swagger-invalid-exception'
+require_relative '../swagger-parameter-helper'
+
+module Sinatra
+
+  module SwaggerExposer
+
+    module Configuration
+
+      module SwaggerConfigurationUtilities
+
+        include ::Sinatra::SwaggerExposer::SwaggerParameterHelper
+
+        def ref_to_type(type)
+          {'$ref' => "#/definitions/#{type}"}
+        end
+
+        def hash_to_swagger(hash)
+          result = {}
+          hash.each_pair do |key, value|
+            result[key] = value.to_swagger
+          end
+          result
+        end
+
+        # Transform a type into a String
+        # @return [String]
+        def type_to_s(value)
+          if [TrueClass, FalseClass].include? value
+            TYPE_BOOLEAN
+          elsif value == DateTime
+            TYPE_DATE_TIME
+          elsif value.is_a? Class
+            value.to_s.downcase
+          else
+            value
+          end
+        end
+
+        def get_type(type, possible_values)
+          @type = type
+          if type.nil?
+            raise SwaggerInvalidException.new('Type is nil')
+          elsif type.is_a?(String) || @type.is_a?(Class)
+            @type = type_to_s(@type)
+            check_type(@type, possible_values)
+          elsif @type.is_a? Array
+            @items = type_to_s(get_array_type(@type))
+            check_type(@items, possible_values)
+            @type = TYPE_ARRAY
+          else
+            raise SwaggerInvalidException.new("Type [#{@type}] of has an unknown type, should be a class, a string or an array")
+          end
+        end
+
+        # Validate if a parameter is in a list of available values
+        # @param params [Hash] the parameters
+        # @param allowed_values [Enumerable, #include?] the allowed values
+        # @param ignored_values [Enumerable, #include?] values to ignore
+        # @return [Hash] the filtered hash
+        def white_list_params(params, allowed_values, ignored_values = [])
+          result = {}
+          params.each_pair do |key, value|
+            if allowed_values.include? key
+              result[key] = value
+            elsif !ignored_values.include?(key)
+              raise SwaggerInvalidException.new("Unknown property [#{key}] with value [#{value}]#{list_or_none(allowed_values, 'properties')}")
+            end
+          end
+          result
+        end
+
+        def list_or_none(list, name)
+          if list.empty?
+            ", no available #{name}"
+          else
+            ", possible #{name} are #{list.join(', ')}"
+          end
+        end
+
+        # Validate if a value is suitable for a name
+        # @param name [String] the name
+        # @return [NilClass]
+        def check_name(name)
+          unless name.is_a?(String) || name.is_a?(Symbol)
+            raise SwaggerInvalidException.new("Name [#{name}] should be a string or a symbol")
+          end
+          name = name.to_s
+          if name.empty?
+            raise SwaggerInvalidException.new('Name should not be empty')
+          end
+        end
+
+        private
+
+        def get_array_type(array)
+          if array.empty?
+            raise SwaggerInvalidException.new('Type is an empty array, you should specify a type as the array content')
+          elsif array.length > 1
+            raise SwaggerInvalidException.new("Type [#{array}] has more than one entry, it should only have one")
+          else
+            type_to_s(array[0])
+          end
+        end
+
+        # 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
+
+      end
+
+    end
+
+  end
+
+end

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

@@ -1,7 +1,8 @@
 require_relative '../swagger-invalid-exception'
-require_relative '../swagger-utilities'
+
 require_relative 'swagger-parameter-validation-helper'
 require_relative 'swagger-type-property'
+require_relative 'swagger-configuration-utilities'
 
 module Sinatra
 
@@ -11,7 +12,7 @@ module Sinatra
 
       class SwaggerEndpointParameter
 
-        include Sinatra::SwaggerExposer::SwaggerUtilities
+        include SwaggerConfigurationUtilities
         include SwaggerParameterValidationHelper
 
         attr_reader :type, :name, :required, :default, :params, :items, :how_to_pass
@@ -23,15 +24,9 @@ module Sinatra
         # @param required [TrueClass] if the parameter is required
         # @param type [String] the type name
         # @param params [Hash] parameters
-        # @param known_types [String] know custom types names
+        # @param known_types [Array<String>] known custom types names
         def initialize(name, description, how_to_pass, required, type, params, known_types)
-          unless name.is_a?(String) || name.is_a?(Symbol)
-            raise SwaggerInvalidException.new("Name [#{name}] should be a string or a symbol")
-          end
-          name = name.to_s
-          if name.empty?
-            raise SwaggerInvalidException.new('Name should not be empty')
-          end
+          check_name(name)
           @name = name
 
           if description
@@ -66,9 +61,9 @@ module Sinatra
         # @return [Hash]
         def to_swagger
           result = {
-              :name => @name,
-              :in => @how_to_pass,
-              :required => @required
+            :name => @name,
+            :in => @how_to_pass,
+            :required => @required
           }
 
           if @type
@@ -102,13 +97,13 @@ module Sinatra
 
         def to_s
           {
-              :name => @name,
-              :in => @how_to_pass,
-              :required => @required,
-              :type => @type,
-              :items => @items,
-              :description => @description,
-              :params => @params,
+            :name => @name,
+            :in => @how_to_pass,
+            :required => @required,
+            :type => @type,
+            :items => @items,
+            :description => @description,
+            :params => @params,
           }.to_json
         end
 

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

@@ -1,6 +1,7 @@
-require_relative '../swagger-utilities'
 require_relative '../swagger-invalid-exception'
 
+require_relative 'swagger-configuration-utilities'
+
 module Sinatra
 
   module SwaggerExposer
@@ -9,15 +10,38 @@ module Sinatra
 
       class SwaggerEndpointResponse
 
-        include SwaggerUtilities
+        include SwaggerConfigurationUtilities
+
+        attr_reader :type, :items
 
         RESPONSE_PRIMITIVES_FILES = PRIMITIVE_TYPES + [TYPE_FILE]
 
-        def initialize(type, description, known_types)
-          get_type(type, known_types + RESPONSE_PRIMITIVES_FILES)
+        # @param type the type
+        # @param description [String] the description
+        # @param known_types [Array<String>] known custom types names
+        # @param headers [Array<String] the headers names
+        # @param known_headers [Sinatra::SwaggerExposer::Configuration::SwaggerResponseHeaders] the known headers
+        def initialize(type, description, known_types, headers, known_headers)
+          if type
+            get_type(type, known_types + RESPONSE_PRIMITIVES_FILES)
+          end
+
           if description
             @description = description
           end
+
+          @headers = {}
+          headers.each do |header_name|
+            header_name = header_name.to_s
+            if @headers.key? header_name
+              raise SwaggerInvalidException.new("Duplicated header_name [#{header_name}]")
+            end
+            unless known_headers.key? header_name
+              raise SwaggerInvalidException.new("Unknown header_name [#{header_name}]")
+            end
+            @headers[header_name] = known_headers[header_name]
+          end
+
         end
 
         def to_swagger
@@ -47,14 +71,22 @@ module Sinatra
             result[:description] = @description
           end
 
+          unless @headers.empty?
+            swagged_headers = {}
+            @headers.each_pair do |name, value|
+              swagged_headers[name] = value.to_swagger
+            end
+            result[:headers] = swagged_headers
+          end
+
           result
         end
 
         def to_s
           {
-              :type => @type,
-              :items => @items,
-              :description => @description,
+            :type => @type,
+            :items => @items,
+            :description => @description,
           }.to_json
         end
 

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

@@ -1,5 +1,6 @@
 require_relative '../swagger-invalid-exception'
-require_relative '../swagger-utilities'
+
+require_relative 'swagger-configuration-utilities'
 
 module Sinatra
 
@@ -10,16 +11,26 @@ module Sinatra
       # An endpoint
       class SwaggerEndpoint
 
-        include Sinatra::SwaggerExposer::SwaggerUtilities
+        include SwaggerConfigurationUtilities
 
-        attr_reader :path, :type, :parameters
+        attr_reader :path, :type, :parameters, :responses, :produces
 
+        # @param type [String] the http verb
+        # @param sinatra_path [String] the sinatra path
+        # @param parameters [Array<Sinatra::SwaggerExposer::Configuration::SwaggerEndpoint>] the endpoint parameters
+        # @param responses [Hash<Integer, Sinatra::SwaggerExposer::Configuration::SwaggerEndpointResponse>] the endpoint possible responses
+        # @param summary [String] a summary for the endpoint
+        # @param description [String] a description for the endpoint
+        # @param tags [Array<String>] a list of tags
+        # @param explicit_path [String] an explicit path if the sinatra path is a regex
+        # @param produces [Array<String>] the result types
         def initialize(type, sinatra_path, parameters, responses, summary, description, tags, explicit_path, produces)
           @type = type
           @path = swagger_path(sinatra_path, explicit_path)
 
           @parameters = parameters
           @responses = responses
+          @produces = produces
 
           @attributes = {}
           if summary
@@ -36,6 +47,8 @@ module Sinatra
           end
         end
 
+        # Return a swagger version
+        # @return [Hash]
         def to_swagger
           result = @attributes.clone
 
@@ -74,11 +87,11 @@ module Sinatra
 
         def to_s
           {
-              :type => @type,
-              :path => @path,
-              :attributes => @attributes,
-              :parameters => @parameters,
-              :responses => @responses,
+            :type => @type,
+            :path => @path,
+            :attributes => @attributes,
+            :parameters => @parameters,
+            :responses => @responses,
           }.to_json
         end
 

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

@@ -1,5 +1,6 @@
 require_relative '../swagger-invalid-exception'
-require_relative '../swagger-utilities'
+
+require_relative 'swagger-configuration-utilities'
 
 module Sinatra
 
@@ -10,7 +11,7 @@ module Sinatra
       # The info declaration
       class SwaggerInfo
 
-        include SwaggerUtilities
+        include SwaggerConfigurationUtilities
 
         def initialize(values)
           @values = process(values, 'info', INFO_FIELDS, values)
@@ -18,12 +19,12 @@ module Sinatra
 
         # 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},
+          :version => String,
+          :title => String,
+          :description => String,
+          :termsOfService => String,
+          :contact => {:name => String, :email => String, :url => String},
+          :license => {:name => String, :url => String},
         }
 
         # Recursive function