apipierails3 0.0.1

data/lib/apipie/routes_formatter.rb

@@ -0,0 +1,33 @@
+module Apipie
+  class RoutesFormatter
+    API_METHODS = %w{GET POST PUT PATCH OPTIONS DELETE}
+
+    # The entry method called by Apipie to extract the array
+    # representing the api dsl from the routes definition.
+    def format_routes(rails_routes, args)
+      rails_routes.map { |rails_route| format_route(rails_route, args) }
+    end
+
+    def format_route(rails_route, args)
+      { :path => format_path(rails_route),
+        :verb => format_verb(rails_route),
+        :desc => args[:desc],
+        :options => args[:options] }
+    end
+
+    def format_path(rails_route)
+      rails_route.path.spec.to_s.gsub('(.:format)', '')
+    end
+
+    def format_verb(rails_route)
+      verb = API_METHODS.select{|defined_verb| defined_verb =~ /\A#{rails_route.verb}\z/}
+      if verb.count != 1
+        verb = API_METHODS.select{|defined_verb| defined_verb == rails_route.constraints[:method]}
+        if verb.blank?
+          raise "Unknow verb #{rails_route.path.spec.to_s}"
+        end
+      end
+      verb.first
+    end
+  end
+end

data/lib/apipie/routing.rb

@@ -0,0 +1,16 @@
+module Apipie
+  module Routing
+    module MapperExtensions
+      def apipie(options = {})
+        namespace "apipie", :path => Apipie.configuration.doc_base_url do
+          get 'apipie_checksum', :to => "apipies#apipie_checksum", :format => "json"
+          constraints(:version => /[^\/]+/, :resource => /[^\/]+/, :method => /[^\/]+/) do
+            get(options.reverse_merge("(:version)/(:resource)/(:method)" => "apipies#index", :as => :apipie))
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.send :include, Apipie::Routing::MapperExtensions

data/lib/apipie/rspec/response_validation_helper.rb

@@ -0,0 +1,192 @@
+#----------------------------------------------------------------------------------------------
+# response_validation_helper.rb:
+#
+# this is an rspec utility to allow validation of responses against the swagger schema generated
+# from the Apipie 'returns' definition for the call.
+#
+#
+# to use this file in a controller rspec you should
+# require 'apipie/rspec/response_validation_helper' in the spec file
+#
+#
+# this utility provides two mechanisms:  matcher-based validation and auto-validation
+#
+#   matcher-based: an rspec matcher allowing 'expect(response).to match_declared_responses'
+#   auto-validation: all responses returned from 'get', 'post', etc. are automatically tested
+#
+# ===================================
+# Matcher-based validation - example
+# ===================================
+# Assume the file 'my_controller_spec.rb':
+#
+#     require 'apipie/rspec/response_validation_helper'
+#
+#     RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+#
+#     describe "GET stuff with response validation" do
+#       render_views   # this makes sure the 'get' operation will actually
+#                      # return the rendered view even though this is a Controller spec
+#
+#       it "does something" do
+#         response = get :index, {format: :json}
+#
+#         # the following expectation will fail if the returned object
+#         # does not match the 'returns' declaration in the Controller,
+#         # or if there is no 'returns' declaration for the returned
+#         # HTTP status code
+#         expect(response).to match_declared_responses
+#       end
+#     end
+#
+#
+# ===================================
+# Auto-validation
+# ===================================
+# To use auto-validation, at the beginning of the block in which you want to turn on validation:
+#    -) turn on view rendering (by stating 'render_views')
+#    -) turn on response validation by stating 'auto_validate_rendered_views'
+#
+# For example, assume the file 'my_controller_spec.rb':
+#
+#     require 'apipie/rspec/response_validation_helper'
+#
+#     RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+#
+#     describe "GET stuff with response validation" do
+#       render_views
+#       auto_validate_rendered_views
+#
+#       it "does something" do
+#         get :index, {format: :json}
+#       end
+#       it "does something else" do
+#         get :another_index, {format: :json}
+#       end
+#     end
+#
+#     describe "GET stuff without response validation" do
+#       it "does something" do
+#         get :index, {format: :json}
+#       end
+#       it "does something else" do
+#         get :another_index, {format: :json}
+#       end
+#     end
+#
+#
+# Once this is done, responses from http operations ('get', 'post', 'delete', etc.)
+# will fail the test if the response structure does not match the 'returns' declaration
+# on the method (for the actual HTTP status code), or if there is no 'returns' declaration
+# for the HTTP status code.
+#----------------------------------------------------------------------------------------------
+
+
+#----------------------------------------------------------------------------------------------
+# Response validation: core logic  (used by auto-validation and manual-validation mechanisms)
+#----------------------------------------------------------------------------------------------
+class ActionController::Base
+  module Apipie::ControllerValidationHelpers
+    # this method is injected into ActionController::Base in order to
+    # get access to the names of the current controller, current action, as well as to the response
+    def schema_validation_errors_for_response
+      unprocessed_schema = Apipie::json_schema_for_method_response(controller_name, action_name, response.code, true)
+
+      if unprocessed_schema.nil?
+        err = "no schema defined for #{controller_name}##{action_name}[#{response.code}]"
+        return [nil, [err], RuntimeError.new(err)]
+      end
+
+      schema = JSON.parse(JSON(unprocessed_schema))
+
+      error_list = JSON::Validator.fully_validate(schema, response.body, :strict => false, :version => :draft4, :json => true)
+
+      error_object = Apipie::ResponseDoesNotMatchSwaggerSchema.new(controller_name, action_name, response.code, error_list, schema, response.body)
+
+      [schema, error_list, error_object]
+    rescue Apipie::NoDocumentedMethod
+      [nil, [], nil]
+    end
+  end
+
+end
+
+module Apipie
+  def self.print_validation_errors(validation_errors, schema, response, error_object=nil)
+    Rails.logger.warn(validation_errors.to_s)
+    if Rails.env.test?
+      puts "schema validation errors:"
+      validation_errors.each { |e| puts "--> #{e.to_s}" }
+      puts "schema:  #{schema.nil? ? '<none>' : JSON(schema)}"
+      puts "response: #{response.body}"
+      raise error_object if error_object
+    end
+  end
+end
+
+#---------------------------------
+# Manual-validation (RSpec matcher)
+#---------------------------------
+RSpec::Matchers.define :match_declared_responses do
+  match do |actual|
+    (schema, validation_errors) = subject.send(:schema_validation_errors_for_response)
+    valid = (validation_errors == [])
+    Apipie::print_validation_errors(validation_errors, schema, response) unless valid
+
+    valid
+  end
+end
+
+
+#---------------------------------
+# Auto-validation logic
+#---------------------------------
+module RSpec::Rails::ViewRendering
+  # Augment the RSpec DSL
+  module ClassMethods
+    def auto_validate_rendered_views
+      before do
+        @is_response_validation_on = true
+      end
+
+      after do
+        @is_response_validation_on = false
+      end
+    end
+  end
+end
+
+
+ActionController::TestCase::Behavior.instance_eval do
+  # instrument the 'process' method in ActionController::TestCase to enable response validation
+  module Apipie::ResponseValidationHelpers
+    @is_response_validation_on = false
+    def process(*args)
+      result = super(*args)
+      validate_response if @is_response_validation_on
+
+      result
+    end
+
+    def validate_response
+      controller.send(:validate_response_and_abort_with_info_if_errors)
+    end
+  end
+
+end
+
+
+class ActionController::Base
+  module Apipie::ControllerValidationHelpers
+    def validate_response_and_abort_with_info_if_errors
+
+      (schema, validation_errors, error_object) = schema_validation_errors_for_response
+
+      valid = (validation_errors == [])
+      if !valid
+        Apipie::print_validation_errors(validation_errors, schema, response, error_object)
+      end
+    end
+  end
+end
+
+

data/lib/apipie/see_description.rb

@@ -0,0 +1,39 @@
+module Apipie
+
+  class SeeDescription
+
+    attr_reader :link, :description
+
+    def initialize(args)
+      if args.first.is_a? Hash
+        args = args.first
+      elsif args.count == 2
+        if args.last.is_a? Hash
+          args = {:link => args.first}.merge(args.last)
+        else
+          args = {:link => args.first, :description => args.second}
+        end
+      elsif args.count == 1 && args.first.is_a?(String)
+        args = {:link => args.first, :description => args.first}
+      else
+        raise ArgumentError "ApipieError: Bad use of see method."
+      end
+      @link = args[:link] || args['link']
+      @description = args[:desc] || args[:description] || args['desc'] || args['description']
+    end
+
+    def to_json
+      {:link => see_url, :description => description}
+    end
+
+    def see_url
+      method_description = Apipie[@link]
+      if method_description.nil?
+        raise ArgumentError.new("Method #{@link} referenced in 'see' does not exist.")
+      end
+      method_description.doc_url
+    end
+
+  end
+
+end

data/lib/apipie/static_dispatcher.rb

@@ -0,0 +1,69 @@
+module Apipie
+
+  class FileHandler
+    def initialize(root)
+      @root          = root.chomp('/')
+      @compiled_root = /^#{Regexp.escape(root)}/
+      @file_server   = ::Rack::File.new(@root)
+    end
+
+    def match?(path)
+      # Replace all null bytes
+      path = ::Rack::Utils.unescape(path || '').gsub(/\x0/, '')
+
+      full_path = path.empty? ? @root : File.join(@root, path)
+      paths = "#{full_path}#{ext}"
+
+      matches = Dir[paths]
+      match = matches.detect { |m| File.file?(m) }
+      if match
+        match.sub!(@compiled_root, '')
+        match
+      end
+    end
+
+    def call(env)
+      @file_server.call(env)
+    end
+
+    def ext
+      @ext ||= begin
+        ext = cache_extension
+        "{,#{ext},/index#{ext}}"
+      end
+    end
+
+    def cache_extension
+      if ::ActionController::Base.respond_to?(:default_static_extension)
+        ::ActionController::Base.default_static_extension
+      else
+        ::ActionController::Base.page_cache_extension
+      end
+
+    end
+  end
+
+  class StaticDispatcher
+    # Dispatches the static files. Similar to ActionDispatch::Static, but
+    # it supports different baseurl configurations
+    def initialize(app, path)
+      @app = app
+      @file_handler = Apipie::FileHandler.new(path)
+    end
+
+    def call(env)
+      @baseurl ||= Apipie.configuration.doc_base_url
+      case env['REQUEST_METHOD']
+      when 'GET', 'HEAD'
+        path = env['PATH_INFO'].sub("#{@baseurl}/","/apipie/").chomp('/')
+
+        if match = @file_handler.match?(path)
+          env["PATH_INFO"] = match
+          return @file_handler.call(env)
+        end
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/apipie/swagger_generator.rb

@@ -0,0 +1,707 @@
+module Apipie
+
+  #--------------------------------------------------------------------------
+  # Configuration.  Should be moved to Apipie config.
+    #--------------------------------------------------------------------------
+  class SwaggerGenerator
+    require 'json'
+    require 'ostruct'
+    require 'open3'
+    require 'zlib' if Apipie.configuration.swagger_generate_x_computed_id_field?
+
+    attr_reader :computed_interface_id
+
+    def initialize(apipie)
+      @apipie = apipie
+      @issued_warnings = []
+    end
+
+    def params_in_body?
+      Apipie.configuration.swagger_content_type_input == :json
+    end
+
+    def params_in_body_use_reference?
+      Apipie.configuration.swagger_json_input_uses_refs
+    end
+
+    def responses_use_reference?
+      Apipie.configuration.swagger_responses_use_refs?
+    end
+
+    def include_warning_tags?
+      Apipie.configuration.swagger_include_warning_tags
+    end
+
+
+    def generate_from_resources(version, resources, method_name, lang, clear_warnings=false)
+      init_swagger_vars(version, lang, clear_warnings)
+
+      @lang = lang
+      @only_method = method_name
+      add_resources(resources)
+
+      @swagger[:info]["x-computed-id"] = @computed_interface_id if Apipie.configuration.swagger_generate_x_computed_id_field?
+      return @swagger
+    end
+
+
+    #--------------------------------------------------------------------------
+    # Initialization
+    #--------------------------------------------------------------------------
+
+    def init_swagger_vars(version, lang, clear_warnings=false)
+
+      # docs = {
+      #     :name => Apipie.configuration.app_name,
+      #     :info => Apipie.app_info(version, lang),
+      #     :copyright => Apipie.configuration.copyright,
+      #     :doc_url => Apipie.full_url(url_args),
+      #     :api_url => Apipie.api_base_url(version),
+      #     :resources => _resources
+      # }
+
+
+      @swagger = {
+          swagger: '2.0',
+          info: {
+              title: "#{Apipie.configuration.app_name}",
+              description: "#{Apipie.app_info(version, lang)}#{Apipie.configuration.copyright}",
+              version: "#{version}",
+              "x-copyright" => Apipie.configuration.copyright,
+          },
+          basePath: Apipie.api_base_url(version),
+          consumes: [],
+          paths: {},
+          definitions: {},
+          tags: [],
+      }
+
+      if Apipie.configuration.swagger_api_host
+        @swagger[:host] = Apipie.configuration.swagger_api_host
+      end
+
+      if params_in_body?
+        @swagger[:consumes] = ['application/json']
+        @swagger[:info][:title] += " (params in:body)"
+      else
+        @swagger[:consumes] = ['application/x-www-form-urlencoded', 'multipart/form-data']
+        @swagger[:info][:title] += " (params in:formData)"
+      end
+
+      @paths = @swagger[:paths]
+      @definitions = @swagger[:definitions]
+      @tags = @swagger[:tags]
+
+      @issued_warnings = [] if clear_warnings || @issued_warnings.nil?
+      @computed_interface_id = 0
+
+      @current_lang = lang
+    end
+
+    #--------------------------------------------------------------------------
+    # Engine interface methods
+    #--------------------------------------------------------------------------
+
+    def add_resources(resources)
+      resources.each do |resource_name, resource_defs|
+        add_resource_description(resource_name, resource_defs)
+        add_resource_methods(resource_name, resource_defs)
+      end
+    end
+
+    def add_resource_methods(resource_name, resource_defs)
+      resource_defs._methods.each do |apipie_method_name, apipie_method_defs|
+        add_ruby_method(@paths, apipie_method_defs)
+      end
+    end
+
+
+    #--------------------------------------------------------------------------
+    # Logging, debugging and regression-testing utilities
+    #--------------------------------------------------------------------------
+
+    def ruby_name_for_method(method)
+      return "<no method>" if method.nil?
+      method.resource.controller.name + "#" + method.method
+    end
+
+
+    def warn_missing_method_summary() warn 100, "missing short description for method"; end
+    def warn_added_missing_slash(path) warn 101,"added missing / at beginning of path: #{path}"; end
+    def warn_no_return_codes_specified()  warn 102,"no return codes ('errors') specified"; end
+    def warn_hash_without_internal_typespec(param_name)  warn 103,"the parameter :#{param_name} is a generic Hash without an internal type specification"; end
+    def warn_optional_param_in_path(param_name) warn 104, "the parameter :#{param_name} is 'in-path'.  Ignoring 'not required' in DSL"; end
+    def warn_optional_without_default_value(param_name) warn 105,"the parameter :#{param_name} is optional but default value is not specified (use :default_value => ...)"; end
+    def warn_param_ignored_in_form_data(param_name) warn 106,"ignoring param :#{param_name} -- cannot include Hash without fields in a formData specification"; end
+    def warn_path_parameter_not_described(name,path) warn 107,"the parameter :#{name} appears in the path #{path} but is not described"; end
+    def warn_inferring_boolean(name) warn 108,"the parameter [#{name}] is Enum with [true,false] values. Inferring 'boolean'"; end
+
+    def warn(warning_num, msg)
+      suppress = Apipie.configuration.swagger_suppress_warnings
+      return if suppress == true
+      return if suppress.is_a?(Array) && suppress.include?(warning_num)
+
+      method_id = ruby_name_for_method(@current_method)
+      warning_id = "#{method_id}#{warning_num}#{msg}"
+
+      if @issued_warnings.include?(warning_id)
+        # Already issued this warning for the current method
+        return
+      end
+
+      print "WARNING (#{warning_num}): [#{method_id}] -- #{msg}\n"
+      @issued_warnings.push(warning_id)
+      @warnings_issued = true
+    end
+
+    def info(msg)
+      print "--- INFO: [#{ruby_name_for_method(@current_method)}] -- #{msg}\n"
+    end
+
+
+    # the @computed_interface_id is a number that is uniquely derived from the list of operations
+    # added to the swagger definition (in an order-dependent way).
+    # it can be used for regression testing, allowing some differentiation between changes that
+    # result from changes to the input and those that result from changes to the generation
+    # algorithms.
+    # note that at the moment, this only takes operation ids into account, and ignores parameter
+    # definitions, so it's only partially useful.
+    def include_op_id_in_computed_interface_id(op_id)
+      @computed_interface_id = Zlib::crc32("#{@computed_interface_id} #{op_id}") if Apipie.configuration.swagger_generate_x_computed_id_field?
+    end
+
+    #--------------------------------------------------------------------------
+    # Create a tag description for a described resource
+    #--------------------------------------------------------------------------
+
+    def tag_name_for_resource(resource)
+      # resource.controller
+      resource._id
+    end
+
+    def add_resource_description(resource_name, resource)
+      if resource._full_description
+        @tags << {
+            name: tag_name_for_resource(resource),
+            description: Apipie.app.translate(resource._full_description, @current_lang)
+        }
+      end
+    end
+
+    #--------------------------------------------------------------------------
+    # Create swagger definitions for a ruby method
+    #--------------------------------------------------------------------------
+
+    def add_ruby_method(paths, ruby_method)
+
+      if @only_method
+        return unless ruby_method.method == @only_method
+      else
+        return if !ruby_method.show
+      end
+
+      for api in ruby_method.apis do
+        # controller: ruby_method.resource.controller.name,
+
+        path = swagger_path(api.path)
+        paths[path] ||= {}
+        methods = paths[path]
+        @current_method = ruby_method
+
+        @warnings_issued = false
+        responses = swagger_responses_hash_for_method(ruby_method)
+        if include_warning_tags?
+          warning_tags = @warnings_issued ? ['warnings issued'] : []
+        else
+          warning_tags = []
+        end
+
+        op_id = swagger_op_id_for_path(api.http_method, api.path)
+
+        include_op_id_in_computed_interface_id(op_id)
+
+        method_key = api.http_method.downcase
+        @current_http_method = method_key
+
+        methods[method_key] = {
+            tags: [tag_name_for_resource(ruby_method.resource)] + warning_tags + ruby_method.tag_list.tags,
+            consumes: params_in_body? ? ['application/json'] : ['application/x-www-form-urlencoded', 'multipart/form-data'],
+            operationId: op_id,
+            summary: Apipie.app.translate(api.short_description, @current_lang),
+            parameters: swagger_params_array_for_method(ruby_method, api.path),
+            responses: responses,
+            description: ruby_method.full_description
+        }
+
+        if methods[method_key][:summary].nil?
+          methods[method_key].delete(:summary)
+          warn_missing_method_summary
+        end
+      end
+    end
+
+    #--------------------------------------------------------------------------
+    # Utilities for conversion of ruby syntax to swagger syntax
+    #--------------------------------------------------------------------------
+
+    def swagger_path(str)
+      str = str.gsub(/:(\w+)/, '{\1}')
+      str = str.gsub(/\/$/, '')
+
+      if str[0] != '/'
+        warn_added_missing_slash(str)
+        str = '/' + str
+      end
+      str
+    end
+
+    def remove_colons(str)
+      str.gsub(":", "_")
+    end
+
+    def swagger_op_id_for_method(method)
+      remove_colons method.resource.controller.name + "::" + method.method
+    end
+
+    def swagger_id_for_typename(typename)
+      typename
+    end
+
+    def swagger_op_id_for_path(http_method, path)
+      # using lowercase http method, because the 'swagger-codegen' tool outputs
+      # strange method names if the http method is in uppercase
+      http_method.downcase + path.gsub(/\//,'_').gsub(/:(\w+)/, '\1').gsub(/_$/,'')
+    end
+
+    class SwaggerTypeWithFormat
+      attr_reader :str_format
+      def initialize(type, str_format)
+        @type = type
+        @str_format = str_format
+      end
+
+      def to_s
+        @type
+      end
+
+      def ==(other)
+        other.to_s == self.to_s
+      end
+    end
+
+    def lookup
+      @lookup ||= {
+        numeric: "number",
+        hash: "object",
+        array: "array",
+
+        # see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
+        integer: SwaggerTypeWithFormat.new("integer", "int32"),
+        long: SwaggerTypeWithFormat.new("integer", "int64"),
+        number: SwaggerTypeWithFormat.new("number", nil),  # here just for completeness
+        float: SwaggerTypeWithFormat.new("number", "float"),
+        double: SwaggerTypeWithFormat.new("number", "double"),
+        string: SwaggerTypeWithFormat.new("string", nil),  # here just for completeness
+        byte: SwaggerTypeWithFormat.new("string", "byte"),
+        binary: SwaggerTypeWithFormat.new("string", "binary"),
+        boolean: SwaggerTypeWithFormat.new("boolean", nil),  # here just for completeness
+        date: SwaggerTypeWithFormat.new("string", "date"),
+        dateTime: SwaggerTypeWithFormat.new("string", "date-time"),
+        password: SwaggerTypeWithFormat.new("string", "password"),
+      }
+    end
+
+
+    def swagger_param_type(param_desc)
+      if param_desc.nil?
+        raise("problem")
+      end
+
+      v = param_desc.validator
+      if v.nil?
+        return "string"
+      end
+
+      if v.class == Apipie::Validator::EnumValidator || (v.respond_to?(:is_enum?) && v.is_enum?)
+        if v.values - [true, false] == [] && [true, false] - v.values == []
+          warn_inferring_boolean(param_desc.name)
+          return "boolean"
+        else
+          return "enum"
+        end
+      elsif v.class == Apipie::Validator::HashValidator
+        # pp v
+      end
+
+
+      return lookup[v.expected_type.to_sym] || v.expected_type
+    end
+
+
+    #--------------------------------------------------------------------------
+    # Responses
+    #--------------------------------------------------------------------------
+
+    def json_schema_for_method_response(method, return_code, allow_nulls)
+      @definitions = {}
+      for response in method.returns
+        if response.code.to_s == return_code.to_s
+          schema = response_schema(response, allow_nulls) if response.code.to_s == return_code.to_s
+          schema[:definitions] = @definitions if @definitions != {}
+          return schema
+        end
+      end
+      nil
+    end
+
+    def json_schema_for_self_describing_class(cls, allow_nulls)
+      adapter = ResponseDescriptionAdapter.from_self_describing_class(cls)
+      response_schema(adapter, allow_nulls)
+    end
+
+    def response_schema(response, allow_nulls=false)
+      begin
+        # no need to warn about "missing default value for optional param" when processing response definitions
+        prev_value = @disable_default_value_warning
+        @disable_default_value_warning = true
+
+        if responses_use_reference? && response.typename
+          schema = {"$ref" => gen_referenced_block_from_params_array(swagger_id_for_typename(response.typename), response.params_ordered, allow_nulls)}
+        else
+          schema = json_schema_obj_from_params_array(response.params_ordered, allow_nulls)
+        end
+
+      ensure
+        @disable_default_value_warning = prev_value
+      end
+
+      if response.is_array? && schema
+        schema = {
+            type: allow_nulls ? ["array","null"] : "array",
+            items: schema
+        }
+      end
+
+      if response.allow_additional_properties
+        schema[:additionalProperties] = true
+      end
+
+      schema
+    end
+
+    def swagger_responses_hash_for_method(method)
+      result = {}
+
+      for error in method.errors
+        error_block = {description: Apipie.app.translate(error.description, @current_lang)}
+        result[error.code] = error_block
+      end
+
+      for response in method.returns
+        swagger_response_block = {
+            description: response.description
+        }
+
+        schema = response_schema(response)
+        swagger_response_block[:schema] = schema if schema
+
+        result[response.code] = swagger_response_block
+      end
+
+      if result.length == 0
+        warn_no_return_codes_specified
+        result[200] = {description: 'ok'}
+      end
+
+      result
+    end
+
+
+
+    #--------------------------------------------------------------------------
+    # Auto-insertion of parameters that are implicitly defined in the path
+    #--------------------------------------------------------------------------
+
+    def param_names_from_path(path)
+      path.scan(/:(\w+)/).map do |ar|
+        ar[0].to_sym
+      end
+    end
+
+    def add_missing_params(method, path)
+      param_names_from_method = method.params.map {|name, desc| name}
+      missing = param_names_from_path(path) - param_names_from_method
+
+      result = method.params
+
+      missing.each do |name|
+        warn_path_parameter_not_described(name, path)
+        result[name.to_sym] = OpenStruct.new({
+                                                 required: true,
+                                                 _gen_added_from_path: true,
+                                                 name: name,
+                                                 validator: Apipie::Validator::NumberValidator.new(nil),
+                                                 options: {
+                                                     in: "path"
+                                                 }
+                                             })
+      end
+
+      result
+    end
+
+    #--------------------------------------------------------------------------
+    # The core routine for creating a swagger parameter definition block.
+    # The output is slightly different when the parameter is inside a schema block.
+    #--------------------------------------------------------------------------
+    def swagger_atomic_param(param_desc, in_schema, name, allow_nulls)
+      def save_field(entry, openapi_key, v, apipie_key=openapi_key, translate=false)
+        if v.key?(apipie_key)
+          if translate
+            entry[openapi_key] = Apipie.app.translate(v[apipie_key], @current_lang)
+          else
+            entry[openapi_key] = v[apipie_key]
+          end
+        end
+      end
+
+      swagger_def = {}
+      swagger_def[:name] = name if !name.nil?
+
+      swg_param_type = swagger_param_type(param_desc)
+      swagger_def[:type] = swg_param_type.to_s
+      if (swg_param_type.is_a? SwaggerTypeWithFormat) && !swg_param_type.str_format.nil?
+        swagger_def[:format] = swg_param_type.str_format
+      end
+
+      if swagger_def[:type] == "array"
+        swagger_def[:items] = {type: "string"}
+      end
+
+      if swagger_def[:type] == "enum"
+        swagger_def[:type] = "string"
+        swagger_def[:enum] = param_desc.validator.values
+      end
+
+      if swagger_def[:type] == "object"  # we only get here if there is no specification of properties for this object
+        swagger_def[:additionalProperties] = true
+        warn_hash_without_internal_typespec(param_desc.name)
+      end
+
+      if param_desc.is_array?
+        new_swagger_def = {
+            items: swagger_def,
+            type: 'array'
+        }
+        swagger_def = new_swagger_def
+        if allow_nulls
+          swagger_def[:type] = [swagger_def[:type], "null"]
+        end
+      end
+
+      if allow_nulls
+        swagger_def[:type] = [swagger_def[:type], "null"]
+      end
+
+      if !in_schema
+        swagger_def[:in] = param_desc.options.fetch(:in, @default_value_for_param_in)
+        swagger_def[:required] = param_desc.required if param_desc.required
+      end
+
+      save_field(swagger_def, :description, param_desc.options, :desc, true) unless param_desc.options[:desc].nil?
+      save_field(swagger_def, :default, param_desc.options, :default_value)
+
+      if param_desc.respond_to?(:_gen_added_from_path) && !param_desc.required
+        warn_optional_param_in_path(param_desc.name)
+        swagger_def[:required] = true
+      end
+
+      if !swagger_def[:required] && !swagger_def.key?(:default)
+        warn_optional_without_default_value(param_desc.name) unless @disable_default_value_warning
+      end
+
+      swagger_def
+    end
+
+
+    #--------------------------------------------------------------------------
+    # JSON schema and referenced-object generation
+    #--------------------------------------------------------------------------
+
+    def ref_to(name)
+      "#/definitions/#{name}"
+    end
+
+
+    def json_schema_obj_from_params_array(params_array, allow_nulls = false)
+      (param_defs, required_params) = json_schema_param_defs_from_params_array(params_array, allow_nulls)
+
+      result = {type: "object"}
+      result[:properties] = param_defs
+      result[:additionalProperties] = false unless Apipie.configuration.swagger_allow_additional_properties_in_response
+      result[:required] = required_params if required_params.length > 0
+
+      param_defs.length > 0 ? result : nil
+    end
+
+    def gen_referenced_block_from_params_array(name, params_array, allow_nulls=false)
+      return ref_to(:name) if @definitions.key(:name)
+
+      schema_obj = json_schema_obj_from_params_array(params_array, allow_nulls)
+      return nil if schema_obj.nil?
+
+      @definitions[name.to_sym] = schema_obj
+      ref_to(name.to_sym)
+    end
+
+    def json_schema_param_defs_from_params_array(params_array, allow_nulls = false)
+      param_defs = {}
+      required_params = []
+
+      params_array ||= []
+
+
+      for param_desc in params_array
+        if !param_desc.respond_to?(:required)
+          # pp param_desc
+          raise ("unexpected param_desc format")
+        end
+
+        required_params.push(param_desc.name.to_sym) if param_desc.required
+
+        param_type = swagger_param_type(param_desc)
+
+        if param_type == "object" && param_desc.validator.params_ordered
+          schema = json_schema_obj_from_params_array(param_desc.validator.params_ordered, allow_nulls)
+          if param_desc.additional_properties
+            schema[:additionalProperties] = true
+          end
+
+          if param_desc.is_array?
+            new_schema = {
+                type: 'array',
+                items: schema
+            }
+            schema = new_schema
+          end
+
+          if allow_nulls
+            # ideally we would write schema[:type] = ["object", "null"]
+            # but due to a bug in the json-schema gem, we need to use anyOf
+            # see https://github.com/ruby-json-schema/json-schema/issues/404
+            new_schema = {
+                anyOf: [schema, {type: "null"}]
+            }
+            schema = new_schema
+          end
+          param_defs[param_desc.name.to_sym] = schema if !schema.nil?
+        else
+          param_defs[param_desc.name.to_sym] = swagger_atomic_param(param_desc, true, nil, allow_nulls)
+        end
+      end
+
+      [param_defs, required_params]
+    end
+
+
+
+    #--------------------------------------------------------------------------
+    # swagger "Params" block generation
+    #--------------------------------------------------------------------------
+
+    def body_allowed_for_current_method
+      !(['get', 'head'].include?(@current_http_method))
+    end
+
+    def swagger_params_array_for_method(method, path)
+
+      swagger_result = []
+      all_params_hash = add_missing_params(method, path)
+
+      body_param_defs_array = all_params_hash.map {|k, v| v if !param_names_from_path(path).include?(k)}.select{|v| !v.nil?}
+      body_param_defs_hash = all_params_hash.select {|k, v| v if !param_names_from_path(path).include?(k)}
+      path_param_defs_hash = all_params_hash.select {|k, v| v if param_names_from_path(path).include?(k)}
+
+      path_param_defs_hash.each{|name,desc| desc.required = true}
+      add_params_from_hash(swagger_result, path_param_defs_hash, nil, "path")
+
+      if params_in_body? && body_allowed_for_current_method
+        if params_in_body_use_reference?
+          swagger_schema_for_body = {"$ref" => gen_referenced_block_from_params_array("#{swagger_op_id_for_method(method)}_input", body_param_defs_array)}
+        else
+          swagger_schema_for_body = json_schema_obj_from_params_array(body_param_defs_array)
+        end
+
+        swagger_body_param = {
+            name: 'body',
+            in: 'body',
+            schema: swagger_schema_for_body
+        }
+        swagger_result.push(swagger_body_param) if !swagger_schema_for_body.nil?
+
+      else
+        add_params_from_hash(swagger_result, body_param_defs_hash)
+      end
+
+      add_headers_from_hash(swagger_result, method.headers) if method.headers.present?
+
+      swagger_result
+    end
+
+
+    def add_headers_from_hash(swagger_params_array, headers)
+      swagger_headers = headers.map do |header|
+        {
+          name: header[:name],
+          in: 'header',
+          required: header[:options][:required],
+          description: header[:description],
+          type:  header[:options][:type] || 'string'
+        }
+
+      end
+      swagger_params_array.push(*swagger_headers)
+    end
+
+
+    def add_params_from_hash(swagger_params_array, param_defs, prefix=nil, default_value_for_in=nil)
+
+      if default_value_for_in
+        @default_value_for_param_in = default_value_for_in
+      else
+        if body_allowed_for_current_method
+          @default_value_for_param_in = "formData"
+        else
+          @default_value_for_param_in = "query"
+        end
+      end
+
+
+      param_defs.each do |name, desc|
+
+        if !prefix.nil?
+          name = "#{prefix}[#{name}]"
+        end
+
+        if swagger_param_type(desc) == "object"
+          if desc.validator.params_ordered
+            params_hash = Hash[desc.validator.params_ordered.map {|desc| [desc.name, desc]}]
+            add_params_from_hash(swagger_params_array, params_hash, name)
+          else
+            warn_param_ignored_in_form_data(desc.name)
+          end
+        else
+          param_entry = swagger_atomic_param(desc, false, name, false)
+          if param_entry[:required]
+            swagger_params_array.unshift(param_entry)
+          else
+            swagger_params_array.push(param_entry)
+          end
+
+        end
+      end
+    end
+
+  end
+
+end