apiculture 0.1.7 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21e9fada9f8ba88c058f19789d597059bb30b055fe92c10e27953c5df6296758
-  data.tar.gz: 7b3c02a5587b6976a2a1a7b11656834824e32887b9dde3922542687fcbe63c71
+  metadata.gz: bd3d6da6eca1e6a1c63d824bfbed2d43d2a74032f966dc6f17df09c6458548c8
+  data.tar.gz: 53581729f4b81574b5bc400786509cfa6f9364fde56486611ae8eab8c3370f8e
 SHA512:
-  metadata.gz: b0818c0fd6c04efa47f0cabcd0927c13516bd293d7486fea8750b7325d260208b3134432ebf43fbc9d7f0321a8ff7b8e5ea07e6f679e59b1df62e0f5f105f1b7
-  data.tar.gz: 853ca12aefe6005ae08432d29f902f6a1584252db87663c08c96a00f47d7b771108e2485f39e7400615e8f54243f68f6abf2e8406a963def5e3821c9ee62a6fc
+  metadata.gz: c2f325148ce9a454206d278f665b583fbd896b442d5f07eecfef481a43143299001c3097eceaf37e2d61866f8f06e5523677ffcad031a9a5811419ce7f84ee9e
+  data.tar.gz: 97159d92a46fef3e7c093c87ce4b80e783a4610c073857f80c74205ddfcabc7d6b019d3d29b1b2a66d5fd2a6fff92a2fef9f2d3c910dc62478613d42e692dabe

data/.gitignore

@@ -1,7 +1,3 @@
-# rcov generated
-coverage
-coverage.data
-
 # rdoc generated
 rdoc
 
@@ -16,7 +12,7 @@ Gemfile.lock
 # jeweler generated
 pkg
 
-# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
 #
 # * Create a file at ~/.gitignore
 # * Include files you want ignored
@@ -48,3 +44,5 @@ pkg
 
 # For rubinius:
 #*.rbc
+
+.ruby-version

data/.travis.yml

@@ -7,5 +7,7 @@ rvm:
   - 2.5
   - 2.6
   - 2.7
+  - 3.0
+  - 3.2
 sudo: false
 cache: bundler

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.2.0
+* Add ruby 3 support
+* Bump `mustermann` dependency to '~> 3'
+
+
+## 0.2.1
+* Add support for nested fields

data/apiculture.gemspec

@@ -4,14 +4,13 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'apiculture/version'
 
 Gem::Specification.new do |s|
-  s.name = "apiculture"
+  s.name = 'apiculture'
   s.version = Apiculture::VERSION
 
-  s.require_paths = ["lib"]
-  s.authors = ["Julik Tarkhanov", "WeTransfer"]
-  s.homepage       = 'http://github.com/wetransfer/zip_tricks'
-  s.description = "A toolkit for building REST APIs on top of Rack"
-  s.email = "me@julik.nl"
+  s.require_paths = ['lib']
+  s.authors = ['Julik Tarkhanov', 'WeTransfer']
+  s.description = 'A toolkit for building REST APIs on top of Rack'
+  s.email = 'me@julik.nl'
 
   # Prevent pushing this gem to RubyGems.org.
   # To allow pushes either set the 'allowed_push_host'
@@ -23,26 +22,26 @@ Gem::Specification.new do |s|
       'public gem pushes.'
   end
 
-  s.files = `git ls-files -z`.split("\x0")
+  s.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^spec/}) }
   s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.md"
+    'LICENSE.txt',
+    'README.md'
   ]
-  s.homepage = "https://github.com/WeTransfer/apiculture"
-  s.licenses = ["MIT"]
-  s.rubygems_version = "2.4.5.1"
-  s.summary = "Sweet API sauce on top of Rack"
+  s.homepage = 'https://github.com/WeTransfer/apiculture'
+  s.licenses = ['MIT']
+  s.rubygems_version = '2.4.5.1'
+  s.summary = 'Sweet API sauce on top of Rack'
 
-  s.add_runtime_dependency 'mustermann', '~> 1'
   s.add_runtime_dependency 'builder', '~> 3'
-  s.add_runtime_dependency 'rdiscount', '~> 2'
   s.add_runtime_dependency 'github-markup', '~> 3'
   s.add_runtime_dependency 'mustache', '~> 1'
+  s.add_runtime_dependency 'mustermann', '~> 3'
+  s.add_runtime_dependency 'rdiscount', '~> 2'
 
+  s.add_development_dependency 'bundler', '~> 2.0'
+  s.add_development_dependency 'cgi'
   s.add_development_dependency 'rack-test'
-  s.add_development_dependency "rspec", "~> 3"
-  s.add_development_dependency "rdoc", "~> 6.0"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "bundler", "~> 1.0"
-  s.add_development_dependency "simplecov", ">= 0"
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rdoc', '~> 6.0'
+  s.add_development_dependency 'rspec', '~> 3'
 end

data/gemfiles/Gemfile.rack-1.x

@@ -9,9 +9,8 @@ gem 'mustache', '~> 1'
 
 group :development do
   gem 'rack-test'
-  gem "rspec", "~> 3.1", '< 3.2'
+  gem "rspec", "~> 3"
   gem "rdoc", "~> 6.0"
-  gem "rake", "~> 10"
-  gem "simplecov", ">= 0"
+  gem "rake"
   gem "bundler"
 end

data/gemfiles/Gemfile.rack-2.x

@@ -9,9 +9,8 @@ gem 'mustache', '~> 1'
 
 group :development do
   gem 'rack-test'
-  gem "rspec", "~> 3.1", '< 3.2'
+  gem "rspec", "~> 3"
   gem "rdoc", "~> 6.0"
-  gem "rake", "~> 10"
-  gem "simplecov", ">= 0"
+  gem "rake"
   gem "bundler"
 end

data/lib/apiculture/app.rb

@@ -13,19 +13,19 @@ class Apiculture::App
     end
 
     def get(url, **options, &handler_blk)
-      define_action :get, url, options, &handler_blk
+      define_action :get, url, **options, &handler_blk
     end
 
     def post(url, **options, &handler_blk)
-      define_action :post, url, options, &handler_blk
+      define_action :post, url, **options, &handler_blk
     end
 
     def put(url, **options, &handler_blk)
-      define_action :put, url, options, &handler_blk
+      define_action :put, url, **options, &handler_blk
     end
 
     def delete(url, **options, &handler_blk)
-      define_action :delete, url, options, &handler_blk
+      define_action :delete, url, **options, &handler_blk
     end
 
     def actions

data/lib/apiculture/openapi_documentation.rb

@@ -8,9 +8,9 @@ module OpenApiDocumentation
       @paths = chunks.select { |chunk| chunk.respond_to?(:http_verb) }
       @data = {
         openapi: '3.0.0',
-        info: { 
-          title: @app.to_s, 
-          version: '0.0.1', 
+        info: {
+          title: @app.to_s,
+          version: '0.0.1',
           description: @app.to_s + " " + chunks.select { |chunk| chunk.respond_to?(:to_markdown) }.map(&:to_markdown).join("\n")
         },
         tags: []
@@ -27,7 +27,7 @@ module OpenApiDocumentation
     end
 
     def spec
-      @data      
+      @data
     end
 
     private
@@ -137,7 +137,7 @@ module OpenApiDocumentation
 
     def build_request_body
       return nil if VERBS_WITHOUT_BODY.include?(@path.http_verb)
-      
+
       body_params = Hash[ @path.parameters.collect do |parameter|
         [parameter.name, {
           type: Util.map_type(parameter.matchable),
@@ -171,7 +171,7 @@ module OpenApiDocumentation
         unless response.jsonable_object_example.nil? || response.jsonable_object_example.empty?
           _response[:content] = {
             'application/json': {
-                schema: 
+                schema:
                   { type: 'object',
                   properties: Util.response_to_schema(response.jsonable_object_example) }
             }
@@ -198,15 +198,27 @@ module OpenApiDocumentation
     }.freeze
 
     def self.response_to_schema(response)
-      schema = {}
-      return nil if response.nil? || response.empty? || response.class == String
-      response.each do |key, value|
-        schema[key] = {
-          type: 'string',
-          example: value.to_s
-        }
+      case response
+      when NilClass
+      when String
+        { type: 'string', example: response }
+      when Integer
+        { type: 'integer', example: response }
+      when Float
+        { type: 'float', example: response }
+      when Array
+        if response.empty?
+          { type: 'array', items: {} }
+        else
+          { type: 'array', items: response.map { |elem| response_to_schema(elem) } }
+        end
+      when Hash
+        response.each_with_object({}) do |(key, val), schema_hash|
+          schema_hash[key] = response_to_schema(val)
+        end
+      else
+        { type: response.class.name.downcase, example: response.to_s }
       end
-      schema
     end
 
     def self.map_type(type)

data/lib/apiculture/sinatra_instance_methods.rb

@@ -4,7 +4,7 @@ require 'json'
 module Apiculture::SinatraInstanceMethods
   NEWLINE = "\n"
   DEFAULT = :__default__
-  
+
   # Convert the given structure to JSON, set the content-type and
   # return the JSON string
   def json_response(structure, status: DEFAULT)
@@ -12,7 +12,7 @@ module Apiculture::SinatraInstanceMethods
     status(status) unless status == DEFAULT
     JSON.pretty_generate(structure)
   end
-  
+
   # Bail out from an action by sending a halt() via Sinatra. Is most useful for
   # handling access denied, invalid resource and other types of situations
   # where you don't want the request to continue, but still would like to
@@ -20,10 +20,10 @@ module Apiculture::SinatraInstanceMethods
   # with it's own JSON means.
   def json_halt(with_error_message, status: 400, **attrs_for_json_response)
     # Pretty-print + newline to be terminal-friendly
-    err_str = JSON.pretty_generate({error: with_error_message}.merge(attrs_for_json_response)) + NEWLINE
+    err_str = JSON.pretty_generate({error: with_error_message}.merge(**attrs_for_json_response)) + NEWLINE
     halt status, {'Content-Type' => 'application/json'}, [err_str]
   end
-  
+
   # Handles the given action via the given class, passing it the instance variables
   # given in the keyword arguments
   def action_result(action_class, **action_ivars)
@@ -31,7 +31,7 @@ module Apiculture::SinatraInstanceMethods
     unless call_result.is_a?(Array) || call_result.is_a?(Hash) || (call_result.nil? && @status == 204)
       raise "Action result should be an Array, a Hash or it can be nil but only if status is 204, instead it was a #{call_result.class}"
     end
-  
+
     json_response call_result if call_result
   end
 end

data/lib/apiculture/version.rb

@@ -1,3 +1,3 @@
 module Apiculture
-  VERSION = '0.1.7'
+  VERSION = '0.2.1'.freeze
 end

data/lib/apiculture.rb

@@ -10,40 +10,40 @@ module Apiculture
   require_relative 'apiculture/timestamp_promise'
   require_relative 'apiculture/app_documentation'
   require_relative 'apiculture/openapi_documentation'
-  
+
   def self.extended(in_class)
     in_class.send(:include, SinatraInstanceMethods)
     super
   end
-  
+
   IDENTITY_PROC = ->(arg) { arg }
-  
+
   AC_APPLY_TYPECAST_PROC = ->(cast_proc_or_method, v) {
     cast_proc_or_method.is_a?(Symbol) ? v.public_send(cast_proc_or_method) : cast_proc_or_method.call(v)
   }
-  
+
   AC_CHECK_PRESENCE_PROC = ->(name_as_string, params) {
     params.has_key?(name_as_string) or raise MissingParameter.new(name_as_string)
   }
-  
+
   AC_CHECK_TYPE_PROC = ->(param, value) {
     param.matchable === value or raise ParameterTypeMismatch.new(param, value.class)
   }
-  
+
   class Parameter < Struct.new(:name, :description, :required, :matchable, :cast_proc_or_method)
     # Return Strings since Sinatra prefers string keys for params{}
     def name_as_string; name.to_s; end
   end
-  
+
   class RouteParameter < Parameter
   end
-  
+
   class PossibleResponse < Struct.new(:http_status_code, :description, :jsonable_object_example)
     def no_body?
       jsonable_object_example.nil?
     end
   end
-  
+
   # Indicates where this API will be mounted. This is only used
   # for the generated documentation. In general, this should match
   # the SCRIPT_NAME of the Sinatra application when it will be called.
@@ -61,13 +61,13 @@ module Apiculture
   def mounted_at(path)
     @apiculture_mounted_at = path.to_s.gsub(/\/$/, '')
   end
-  
+
   # Inserts the generation timestamp into the documentation at this point.
   # The timestamp will be not very precise (to the minute) and in UTC time
   def documentation_build_time!
     apiculture_stack << Apiculture::TimestampPromise
   end
-  
+
   # Inserts a literal Markdown string into the documentation at this point.
   # For instance, if used after an API method declaration, it will insert
   # the header between the API methods in the doc.
@@ -82,7 +82,7 @@ module Apiculture
   def markdown_string(str)
     apiculture_stack << MarkdownSegment.new(str)
   end
-  
+
   # Inserts the contents of the file at +path+ into the documentation, using +markdown_string+.
   # For instance, if used after an API method declaration, it will insert
   # the header between the API methods in the doc.
@@ -95,25 +95,25 @@ module Apiculture
     md = File.read(path_to_markdown).encode(Encoding::UTF_8)
     markdown_string(md)
   end
-  
+
   # Describe the API method that is going to be defined
   def desc(action_description)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.description = action_description.to_s
   end
-  
+
   # Add an optional parameter for the API call
   def param(name, description, matchable, cast: IDENTITY_PROC)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.parameters << Parameter.new(name, description, required=false, matchable, cast)
   end
-  
+
   # Add a requred parameter for the API call
   def required_param(name, description, matchable, cast: IDENTITY_PROC)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.parameters << Parameter.new(name, description, required=true, matchable, cast)
   end
-  
+
   # Describe a parameter that has to be included in the URL of the API call.
   # Route parameters are always required, and all the parameters specified
   # using +route_param+ should also be included in the path given for the route
@@ -122,28 +122,28 @@ module Apiculture
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.route_parameters << RouteParameter.new(name, description, required=false, matchable, cast)
   end
-  
+
   # Add a possible response, specifying the code and the JSON Response by example.
   # Multiple response packages can be specified.
   def responds_with(http_status, description, example_jsonable_object = nil)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.responses << PossibleResponse.new(http_status, description, example_jsonable_object)
   end
-  
+
   DefinitionError = Class.new(StandardError)
   ValidationError = Class.new(StandardError)
-  
+
   class RouteParameterNotInPath < DefinitionError; end
   class ReservedParameter < DefinitionError; end
   class ConflictingParameter < DefinitionError; end
-  
+
   # Gets raised when a parameter is missing
   class MissingParameter < ValidationError
     def initialize(parameter_name)
       super "Missing parameter :#{parameter_name}"
     end
   end
-  
+
   # Gets raised when a parameter is supplied and has a wrong type
   class ParameterTypeMismatch < ValidationError
     def initialize(ac_parameter, received_ruby_type)
@@ -152,7 +152,7 @@ module Apiculture
       super "Received #{received_type}, expected #{expected_type.inspect} for :#{parameter_name}"
     end
   end
-  
+
   # Returns a Proc that calls the strong parameters to check the presence/types
   def parametric_validator_proc_from(parametric_validators, implicitly_defined_route_parameter_names)
     required_params = parametric_validators.select{|e| e.required }
@@ -164,23 +164,23 @@ module Apiculture
       parametric_validators.each do |param|
         param_name = param.name_as_string
         next unless params.has_key?(param_name) # this is checked via required_params
-        
+
         # Apply the type cast and save it (since using our override we can mutate the params)
         value_after_type_cast = AC_APPLY_TYPECAST_PROC.call(param.cast_proc_or_method, params[param_name])
         params[param_name] = value_after_type_cast
-        
+
         # Ensure the typecast value adheres to the enforced Ruby type
         AC_CHECK_TYPE_PROC.call(param, params[param_name])
       end
-      
-      # The following only applies if the app does not use strong_parameters - 
+
+      # The following only applies if the app does not use strong_parameters -
       # this makes use of parameter mutability again to kill the parameters that are not permitted
       # or mentioned in the API specification. We need to keep the params which are specified in the
       # route but not documented via Apiculture though
       unexpected_parameters = Set.new(params.keys.map(&:to_s)) -
         Set.new(parametric_validators.map(&:name).map(&:to_s)) -
         Set.new(implicitly_defined_route_parameter_names.map(&:to_s))
-      
+
       unexpected_parameters.each do | parameter_to_discard |
         # TODO: raise or record a warning
         if env['rack.logger'].respond_to?(:warn)
@@ -190,7 +190,7 @@ module Apiculture
       end
     }
   end
-  
+
   # Serve the documentation for the API at the given URL
   def serve_api_documentation_at(url)
     get(url) do
@@ -198,7 +198,7 @@ module Apiculture
       self.class.api_documentation.to_html
     end
   end
-  
+
   # Returns an +AppDocumentation+ object for all actions defined so far.
   #
   #   MyApi.api_documentation.to_markdown #=> "..."
@@ -213,7 +213,7 @@ module Apiculture
     action_def = (@apiculture_action_definition || ActionDefinition.new)
     action_def.http_verb = http_verb
     action_def.path = path
-    
+
     # Ensure no reserved Sinatra parameters are used
     all_parameter_names = action_def.all_parameter_names_as_strings
     %w( splat captures ).each do | reserved_param |
@@ -221,34 +221,34 @@ module Apiculture
         raise ReservedParameter.new(":#{reserved_param} is a reserved magic parameter name in Sinatra")
       end
     end
-    
+
     # Ensure no conflations between route/req params
     seen_params = {}
-    all_parameter_names.each do |e| 
+    all_parameter_names.each do |e|
       if seen_params[e]
-        raise ConflictingParameter.new(":#{e} mentioned twice as a possible parameter. Note that URL" + 
+        raise ConflictingParameter.new(":#{e} mentioned twice as a possible parameter. Note that URL" +
           " parameters and request parameters share a namespace.")
       else
         seen_params[e] = true
       end
     end
-    
+
     # Ensure the path has the route parameters that were predeclared
     action_def.route_parameters.map(&:name).each do | route_parameter_key |
       unless path.include?(':%s' % route_parameter_key)
         raise RouteParameterNotInPath.new("Parameter :#{route_parameter_key} not present in path #{path.inspect}")
       end
     end
-    
+
     # TODO: ensure all route parameters are documented
-    
+
     # Pick out all the defined parameters and set up a block that can validate them
     # when the action is called. With that, set up the actual Sinatra method that will
     # respond to the request. We take care to preserve all the params that have NOT been documented
     # using Apiculture but _were_ in fact specified in the actual path.
     route_parameter_names = path.scan(/:([^:\/]+)/).flatten.map(&:to_sym)
     parametric_checker_proc = parametric_validator_proc_from(action_def.parameters + action_def.route_parameters, route_parameter_names)
-    public_send(http_verb, path, options) do |*matched_sinatra_route_params|
+    public_send(http_verb, path, **options) do |*matched_sinatra_route_params|
       # Extract all the parameter names from the route path as given to the method
       route_parameters = Hash[route_parameter_names.zip(matched_sinatra_route_params)]
 
@@ -269,13 +269,13 @@ module Apiculture
       # Execute the original action via instance_exec, passing along the route args
       instance_exec(*route_parameters.values, &blk)
     end
-    
+
     # Reset for the subsequent action definition
     @apiculture_action_definition = ActionDefinition.new
     # and store the just defined action for future use
     apiculture_stack << action_def
   end
-  
+
   def apiculture_stack
     @apiculture_actions_and_docs ||= []
     @apiculture_actions_and_docs