apipie-rails 0.5.6 → 0.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37c0e129d50ee2ead759ed4b2ce84fa78ad8b5e0
-  data.tar.gz: f5576d4598603160aa7624578d62aabdccde8ca9
+  metadata.gz: c873515d61e1046750c0ecd967b30f289ac9e3ee
+  data.tar.gz: 1bfaf2d71ca3b995045cf2be2c75e6cf846e25fa
 SHA512:
-  metadata.gz: 98a8f76dd307fc2fa62825a90ecf5e8c7016a9abb5649cfa79b7d4346102d5f442d3a8ecbfdf603239bd956260fb8d9c117b73c77d536491ed538b38e04ade1b
-  data.tar.gz: 2687e565d29cf0be95eb232d8b8ab015c6378eff0ae42bf36459d10ad3836447343333e7730bb8389ee003e380063788b515cdaac9012112c0de1b5de217a35e
+  metadata.gz: 56d02246c13676a616393bd28a25e297e757aa95ce3b41f6e4f6914cb966afa71ade2eb49ca3b53a39fbbccac3b81bd840e212ef9479de687d628d128626d8d3
+  data.tar.gz: 238da70119f0ce29b87ad54b9e0dd903aac41314c79095c75799aeb7226b7ef2abaf78b361e72e7821281dd3e1c21e60a7f5952f51fcff4cb016705ebd993e95

data/.travis.yml

@@ -1,10 +1,11 @@
 language: ruby
 sudo: false
 rvm:
-  - 2.0.0
   - 2.1.7
   - 2.2.3
   - 2.3.3
+  - 2.4.3
+  - 2.5.0
 gemfile:
   - Gemfile.rails41
   - Gemfile.rails42
@@ -20,3 +21,7 @@ matrix:
       gemfile: Gemfile.rails50
     - rvm: 2.1.7
       gemfile: Gemfile.rails51
+    - rvm: 2.4.3
+      gemfile: Gemfile.rails41
+    - rvm: 2.5.0
+      gemfile: Gemfile.rails41

data/CHANGELOG.md

@@ -1,6 +1,14 @@
  Changelog
 ===========
 
+v0.5.7
+------
+
+- Fix example recording with Rails 5 [\#607](https://github.com/Apipie/apipie-rails/pull/607) ([adamruzicka](https://github.com/adamruzicka))
+- Use SHA1 instead of MD5 to enable using APIPIE at FIPS-enables systems [\#605](https://github.com/Apipie/apipie-rails/pull/605) ([iNecas](https://github.com/iNecas))
+- Replaced String\#constantize with String\#safe\_constantize so apipie won't break on a missing constant [\#575](https://github.com/Apipie/apipie-rails/pull/575) ([Haniyya](https://github.com/Haniyya))
+- Added Swagger generation [\#569](https://github.com/Apipie/apipie-rails/pull/569) ([elasti-ron](https://github.com/elasti-ron))
+
 v0.5.6
 ------
 

data/Gemfile

@@ -1 +1 @@
-./Gemfile.rails50
+Gemfile.rails50

data/README.rst

@@ -1154,6 +1154,111 @@ If, for some complex cases, you need to generate/re-generate just part of the ca
 use ``rake apipie:cache cache_part=index`` resp. ``rake apipie:cache cache_part=resources``
 To generate it for different locations for further processing use ``rake apipie:cache OUT=/tmp/apipie_cache``.
 
+====================================
+ Static Swagger (OpenAPI 2.0) files
+====================================
+
+To generate a static Swagger definition file from the api, run ``rake apipie:static_swagger_json``.
+By default the documentation for the default API version is
+used. You can specify the version with ``rake apipie:static_swagger_json[2.0]``. A swagger file will be
+generated for each locale.  The files will be generated in the same location as the static_json files, but
+instead of being named ``schema_apipie[.locale].json``, they will be called ``schema_swagger[.locale].json``.
+
+Specifying default values for parameters
+-----------------------------------------
+Swagger allows method definitions to include an indication of the the default value for each parameter. To include such
+indications, use ``:default_value => <some value>`` in the parameter definition DSL.  For example:
+
+.. code:: ruby
+
+     param :do_something, Boolean, :desc => "take an action", :required => false, :default_value => false
+
+
+Generated Warnings
+-------------------
+The help identify potential improvements to your documentation, the swagger generation process issues warnings if
+it identifies various shortcomings of the DSL documentation. Each warning has a code to allow selective suppression
+(see swagger-specific configuration below)
+
+:100: missing short description for method
+:101: added missing / at beginning of path
+:102: no return codes specified for method
+:103: a parameter is a generic Hash without an internal type specification
+:104: a parameter is an 'in-path' parameter, but specified as 'not required' in the DSL
+:105: a parameter is optional but does not have a default value specified
+:106: a parameter was ommitted from the swagger output because it is a Hash without fields in a formData specification
+:107: a path parameter is not described
+:108: inferring that a parameter type is boolean because described as an enum with [false,true] values
+
+
+
+Swagger-Specific Configuration Parameters
+-------------------------------------------------
+
+There are several configuration parameters that determine the structure of the generated swagger file:
+
+``config.swagger_content_type_input``
+    If the value is ``:form_data`` - the swagger file will indicate that the server consumes the content types
+    ``application/x-www-form-urlencoded`` and ``multipart/form-data``.  Non-path parameters will have the
+    value ``"in": "formData"``.  Note that parameters of type Hash that do not have any fields in them will *be ommitted*
+    from the resulting files, as there is no way to describe them in swagger.
+
+    If the value is ``:json`` - the swagger file will indicate that the server consumes the content type
+    ``application/json``. All non-path parameters will be included in the schema of a single ``"in": "body"`` parameter
+    of type ``object``.
+
+    You can specify the value of this configuration parameter as an additional input to the rake command (e.g.,
+    ``rake apipie:static_swagger_json[2.0,form_data]``).
+
+``config.swagger_json_input_uses_refs``
+    This parameter is only relevant if ``swagger_content_type_input`` is ``:json``.
+
+    If ``true``: the schema of the ``"in": "body"`` parameter of each method is given its own entry in the ``definitions``
+    section, and is referenced using ``$ref`` from the method definition.
+
+    If ``false``: the body parameter definitions are inlined within the method definitions.
+
+``config.swagger_include_warning_tags``
+    If ``true``: in addition to tagging methods with the name of the resource they belong to, methods for which warnings
+    have been issued will be tagged with.
+
+``config.swagger_suppress_warnings``
+    If ``false``: no warnings will be suppressed
+
+    If ``true``: all warnings will be suppressed
+
+    If an array of values (e.g., ``[100,102,107]``), only the warnings identified by the numbers in the array will be suppressed.
+
+``config.swagger_api_host``
+    The value to place in the swagger host field.
+
+    Default is ``localhost:3000``
+
+    If ``nil`` then then host field will not be included.
+
+
+
+Known limitations of the current implementation
+-------------------------------------------------
+* There is currently no way to document the structure and content-type of the data returned from a method
+* Recorded examples are currently not included in the generated swagger file
+* The apipie ``formats`` value is ignored.
+* It is not possible to specify the "consumed" content type on a per-method basis
+* It is not possible to leverage all of the parameter type/format capabilities of swagger
+* Only OpenAPI 2.0 is supported
+
+====================================
+ Dynamic Swagger generation
+====================================
+
+To generate swagger dynamically, use ``http://localhost:3000/apipie.json?type=swagger``.
+
+Note that authorization is not supported for dynamic swagger generation, so if ``config.authorize`` is defined,
+dynamic swagger generation will be disabled.
+
+Dynamically generated swagger is not cached, and is always generated on the fly.
+
+
 ===================
  JSON checksums
 ===================

data/apipie-rails.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency "RedCloth"
   s.add_development_dependency "rake"
   s.add_development_dependency "rdoc"
+  s.add_development_dependency "json-schema", "~> 2.8"
 end

data/app/controllers/apipie/apipies_controller.rb

@@ -14,11 +14,17 @@ module Apipie
       end
     end
 
+
     def index
       params[:version] ||= Apipie.configuration.default_version
 
       get_format
 
+      if params[:type].to_s == 'swagger' && params[:format].to_s == 'json'
+        head :forbidden and return if Apipie.configuration.authorize
+        should_render_swagger = true
+      end
+
       respond_to do |format|
 
         if Apipie.configuration.use_cache?
@@ -31,9 +37,19 @@ module Apipie
         Apipie.load_documentation if Apipie.configuration.reload_controllers? || (Rails.version.to_i >= 4.0 && !Rails.application.config.eager_load)
 
         I18n.locale = @language
-        @doc = Apipie.to_json(params[:version], params[:resource], params[:method], @language)
 
-        @doc = authorized_doc
+        if should_render_swagger
+          prev_warning_value = Apipie.configuration.swagger_suppress_warnings
+          begin
+            Apipie.configuration.swagger_suppress_warnings = true
+            @doc = Apipie.to_swagger_json(params[:version], params[:resource], params[:method], @language)
+          ensure
+            Apipie.configuration.swagger_suppress_warnings = prev_warning_value
+          end
+        else
+          @doc = Apipie.to_json(params[:version], params[:resource], params[:method], @language)
+          @doc = authorized_doc
+        end
 
         format.json do
           if @doc

data/lib/apipie-rails.rb

@@ -17,6 +17,7 @@ require "apipie/validator"
 require "apipie/railtie"
 require 'apipie/extractor'
 require "apipie/version"
+require "apipie/swagger_generator"
 
 if Rails.version.start_with?("3.0")
   warn 'Warning: apipie-rails is not going to support Rails 3.0 anymore in future versions'

data/lib/apipie/apipie_module.rb

@@ -13,6 +13,11 @@ module Apipie
     app.to_json(version, resource_name, method_name, lang)
   end
 
+  def self.to_swagger_json(version = nil, resource_name = nil, method_name = nil, lang = nil, clear_warnings=true)
+    version ||= Apipie.configuration.default_version
+    app.to_swagger_json(version, resource_name, method_name, lang, clear_warnings)
+  end
+
   # all calls delegated to Apipie::Application instance
   def self.method_missing(method, *args, &block)
     app.respond_to?(method) ? app.send(method, *args, &block) : super

data/lib/apipie/application.rb

@@ -1,7 +1,7 @@
 require 'apipie/static_dispatcher'
 require 'apipie/routes_formatter'
 require 'yaml'
-require 'digest/md5'
+require 'digest/sha1'
 require 'json'
 
 module Apipie
@@ -55,7 +55,8 @@ module Apipie
     # this method does in depth search for the route controller
     def route_app_controller(app, route, visited_apps = [])
       if route.defaults[:controller]
-        (route.defaults[:controller].camelize + "Controller").constantize
+        controller_name = (route.defaults[:controller] + 'Controller').camelize
+        controller_name.safe_constantize
       end
     end
 
@@ -239,6 +240,7 @@ module Apipie
       @resource_descriptions ||= HashWithIndifferentAccess.new { |h, version| h[version] = {} }
       @controller_to_resource_id ||= {}
       @param_groups ||= {}
+      @swagger_generator = Apipie::SwaggerGenerator.new(self)
 
       # what versions does the controller belong in (specified by resource_description)?
       @controller_versions ||= Hash.new { |h, controller| h[controller.to_s] = [] }
@@ -253,6 +255,24 @@ module Apipie
       @recorded_examples = nil
     end
 
+    def to_swagger_json(version, resource_name, method_name, lang, clear_warnings=false)
+      return unless valid_search_args?(version, resource_name, method_name)
+
+      # if resource_name is blank, take just resources which have some methods because
+      # we dont want to show eg ApplicationController as resource
+      # otherwise, take only the specified resource
+      _resources = resource_descriptions[version].inject({}) do |result, (k,v)|
+         if resource_name.blank?
+           result[k] = v unless v._methods.blank?
+         else
+           result[k] = v if k == resource_name
+         end
+         result
+       end
+
+      @swagger_generator.generate_from_resources(version,_resources, method_name, lang, clear_warnings)
+    end
+
     def to_json(version, resource_name, method_name, lang)
 
       return unless valid_search_args?(version, resource_name, method_name)
@@ -321,7 +341,7 @@ module Apipie
           all.update(version => Apipie.to_json(version))
         end
       end
-      Digest::MD5.hexdigest(JSON.dump(all_docs))
+      Digest::SHA1.hexdigest(JSON.dump(all_docs))
     end
 
     def checksum

data/lib/apipie/configuration.rb

@@ -7,11 +7,16 @@ module Apipie
       :validate, :validate_value, :validate_presence, :validate_key, :authenticate, :doc_path,
       :show_all_examples, :process_params, :update_checksum, :checksum_path,
       :link_extension, :record, :languages, :translate, :locale, :default_locale,
-      :persist_show_in_doc, :authorize
+      :persist_show_in_doc, :authorize,
+      :swagger_include_warning_tags, :swagger_content_type_input, :swagger_json_input_uses_refs,
+      :swagger_suppress_warnings, :swagger_api_host, :swagger_generate_x_computed_id_field
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
     alias_method :namespaced_resources?, :namespaced_resources
+    alias_method :swagger_include_warning_tags?, :swagger_include_warning_tags
+    alias_method :swagger_json_input_uses_refs?, :swagger_json_input_uses_refs
+    alias_method :swagger_generate_x_computed_id_field?, :swagger_generate_x_computed_id_field
 
     # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
     #
@@ -108,7 +113,7 @@ module Apipie
     # the line above the docs.
     attr_writer :generated_doc_disclaimer
     def generated_doc_disclaimer
-      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENARATING NEXT TIME"
+      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENERATING NEXT TIME"
     end
 
     def use_disqus?
@@ -165,6 +170,12 @@ module Apipie
       @translate = lambda { |str, locale| str }
       @persist_show_in_doc = false
       @routes_formatter = RoutesFormatter.new
+      @swagger_content_type_input = :form_data  # this can be :json or :form_data
+      @swagger_json_input_uses_refs = false
+      @swagger_include_warning_tags = false
+      @swagger_suppress_warnings = false #[105,100,102]
+      @swagger_api_host = "localhost:3000"
+      @swagger_generate_x_computed_id_field = false
     end
   end
 end

data/lib/apipie/extractor.rb

@@ -16,9 +16,7 @@ class Apipie::Railtie
       end
     end
     app.middleware.use ::Apipie::Extractor::Recorder::Middleware
-    ActionController::TestCase::Behavior.instance_eval do
-      prepend Apipie::Extractor::Recorder::FunctionalTestRecording
-    end
+    ActionController::TestCase.send(:prepend, Apipie::Extractor::Recorder::FunctionalTestRecording)
   end
 end
 
@@ -154,7 +152,7 @@ module Apipie
       def update_api_descriptions
         apis_from_docs = all_apis_from_docs
         @apis_from_routes.each do |(controller, action), new_apis|
-          method_key = "#{Apipie.get_resource_name(controller.constantize)}##{action}"
+          method_key = "#{Apipie.get_resource_name(controller.safe_constantize || next)}##{action}"
           old_apis = apis_from_docs[method_key] || []
           new_apis.each do |new_api|
             new_api[:path].sub!(/\(\.:format\)$/,"") if new_api[:path]

data/lib/apipie/swagger_generator.rb

@@ -0,0 +1,545 @@
+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
+    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 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,
+            operationId: op_id,
+            summary: Apipie.app.translate(api.short_description, @current_lang),
+            parameters: swagger_params_array_for_method(ruby_method, api.path),
+            responses: responses
+        }
+
+        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_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
+
+    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
+        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
+
+      lookup = {
+          numeric: "number",
+          hash: "object",
+          array: "array"
+      }
+
+      return lookup[v.expected_type.to_sym] || v.expected_type
+    end
+
+
+    #--------------------------------------------------------------------------
+    # Responses
+    #--------------------------------------------------------------------------
+
+    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
+
+      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=nil)
+      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?
+      swagger_def[:type] = swagger_param_type(param_desc)
+
+      if swagger_def[:type] == "array"
+        swagger_def[:items] = {type: "string"} # TODO: add support for arrays of non-string items
+      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 !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)
+      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)
+      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)
+      (param_defs, required_params) = json_schema_param_defs_from_params_array(params_array)
+
+      result = {type: "object"}
+      result[:properties] = param_defs
+      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)
+      return ref_to(:name) if @definitions.key(:name)
+
+      schema_obj = json_schema_obj_from_params_array(params_array)
+      return nil if schema_obj.nil?
+
+      @definitions[name] = schema_obj
+      ref_to(name)
+    end
+
+    def json_schema_param_defs_from_params_array(params_array)
+      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) 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)
+          param_defs[param_desc.name] = schema if !schema.nil?
+        else
+          param_defs[param_desc.name] = swagger_atomic_param(param_desc, true)
+        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
+
+      swagger_result
+    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)
+          if param_entry[:required]
+            swagger_params_array.unshift(param_entry)
+          else
+            swagger_params_array.push(param_entry)
+          end
+
+        end
+      end
+    end
+    
+  end
+
+end