apipie-rails 0.9.4 → 1.0.0

data/lib/apipie/swagger_generator.rb

@@ -1,569 +1,45 @@
 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)
-
-      @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: {},
-          schemes: Apipie.configuration.swagger_schemes,
-          tags: [],
-          securityDefinitions: Apipie.configuration.swagger_security_definitions,
-          security: Apipie.configuration.swagger_global_security
-      }
-
-      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(Apipie::Generator::Swagger::Warning::MISSING_METHOD_SUMMARY_CODE)
-    end
-
-    def warn_added_missing_slash(path)
-      warn(
-        Apipie::Generator::Swagger::Warning::ADDED_MISSING_SLASH_CODE,
-        { path: path }
-      )
-    end
-
-    def warn_no_return_codes_specified
-      warn(Apipie::Generator::Swagger::Warning::NO_RETURN_CODES_SPECIFIED_CODE)
-    end
-
-    def warn_optional_param_in_path(param_name)
-      warn(
-        Apipie::Generator::Swagger::Warning::OPTIONAL_PARAM_IN_PATH_CODE,
-        { parameter: param_name }
-      )
-    end
-
-    def warn_optional_without_default_value(param_name)
-      warn(
-        Apipie::Generator::Swagger::Warning::OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
-        { parameter: param_name }
-      )
-    end
-
-    def warn_param_ignored_in_form_data(param_name)
-      warn(
-        Apipie::Generator::Swagger::Warning::PARAM_IGNORED_IN_FORM_DATA_CODE,
-        { parameter: param_name }
-      )
-    end
-
-    def warn_path_parameter_not_described(name, path)
-      warn(
-        Apipie::Generator::Swagger::Warning::PATH_PARAM_NOT_DESCRIBED_CODE,
-        { name: name, path: path }
-      )
-    end
-
-    def warn_inferring_boolean(name)
-      warn(
-        Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE,
-        { name: name }
-      )
-    end
-
-    # @param [Integer] warning_code
-    # @param [Hash] message_attributes
-    def warn(warning_code, message_attributes = {})
-      Apipie::Generator::Swagger::Warning.for_code(
-        warning_code,
-        ruby_name_for_method(@current_method),
-        message_attributes
-      ).warn_through_writer
-
-      @warnings_issued = Apipie::Generator::Swagger::WarningWriter.
-        instance.
-        issued_warnings?
-    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 = Apipie::Generator::Swagger::OperationId.from(api).to_s
-
-        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: Apipie.app.translate(ruby_method.full_description, @current_lang)
-        }
-
-        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(%r{/$}, '')
-
-      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_param_type(param_desc)
-      if param_desc.blank?
-        raise ArgumentError, 'param_desc is required'
-      end
-
-      method_id = ruby_name_for_method(@current_method)
-
-      warning = Apipie::Generator::Swagger::Warning.for_code(
-        Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE,
-        method_id,
-        { parameter: param_desc.name }
-      )
-
-      Apipie::Generator::Swagger::TypeExtractor.new(param_desc.validator).
-        extract_with_warnings({ boolean: warning })
-    end
-
-
-    #--------------------------------------------------------------------------
-    # Responses
-    #--------------------------------------------------------------------------
-
-    def json_schema_for_method_response(method, return_code, allow_nulls)
-      @definitions = {}
-      for response in method.returns
-        next unless response.code.to_s == return_code.to_s
-        schema = response_schema(response, allow_nulls)
-        schema[:definitions] = @definitions if @definitions != {}
-        return schema
-      end
-      nil
+    # @param [Array<Apipie::ResourceDescription] resources
+    def self.generate_from_resources(resources, version:, language:, clear_warnings: false)
+      Apipie::Generator::Swagger::Schema.new(
+        resources,
+        version: version,
+        language: language,
+        clear_warnings: clear_warnings
+      ).generate
     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 self.json_schema_for_method_response(method, return_code, allow_nulls)
+      response = method.returns.find { |response| response.code.to_s == return_code.to_s }
 
-    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
+      return if response.blank?
 
-        if responses_use_reference? && response.typename
-          schema = {
-            "$ref" => gen_referenced_block_from_params_array(
-              response.typename,
-              response.params_ordered,
-              allow_nulls
-            )
-          }
-        else
-          schema = Apipie::Generator::Swagger::ParamDescription::Composite.new(
-            response.params_ordered,
-            Apipie::Generator::Swagger::Context.new(
-              allow_null: allow_nulls,
-              http_method: @current_http_method,
-              controller_method: @current_method
-            )
-          ).to_swagger
-        end
+      http_method = method.apis.first.http_method
 
-      ensure
-        @disable_default_value_warning = prev_value
-      end
+      schema = Apipie::Generator::Swagger::MethodDescription::ResponseSchemaService.new(
+        response,
+        allow_null: allow_nulls,
+        http_method: http_method,
+        controller_method: method
+      ).to_swagger
 
-      if response.is_array? && schema
-        schema = {
-            type: allow_nulls ? ["array","null"] : "array",
-            items: schema
-        }
-      end
+      definitions = Apipie::Generator::Swagger::ReferencedDefinitions.instance.definitions
 
-      if response.allow_additional_properties
-        schema[:additionalProperties] = true
+      if definitions.present?
+        schema[:definitions] = definitions
       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: Apipie.app.translate(response.description, @current_lang)
-        }
-
-        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] = Apipie::Generator::Swagger::ParamDescription.
-          create_for_missing_param(method, name)
-      end
-
-      result
-    end
-
-    #--------------------------------------------------------------------------
-    # JSON schema and referenced-object generation
-    #--------------------------------------------------------------------------
-
-    def ref_to(name)
-      "#/definitions/#{name}"
-    end
-
-    def gen_referenced_block_from_params_array(name, params_array, allow_nulls = false)
-      return ref_to(:name) if @definitions.key(:name)
-
-      schema_obj = Apipie::Generator::Swagger::ParamDescription::Composite.new(
-        params_array,
-        Apipie::Generator::Swagger::Context.new(
-          allow_null: allow_nulls,
-          http_method: @current_http_method,
-          controller_method: @current_method
-        )
+    def self.json_schema_for_self_describing_class(cls, allow_nulls)
+      Apipie::Generator::Swagger::MethodDescription::ResponseSchemaService.new(
+        ResponseDescriptionAdapter.from_self_describing_class(cls),
+        allow_null: allow_nulls,
+        http_method: nil,
+        controller_method: nil
       ).to_swagger
-
-      return nil if schema_obj.nil?
-
-      @definitions[name.to_sym] = schema_obj
-      ref_to(name.to_sym)
-    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 =
-            Apipie::Generator::Swagger::ParamDescription::Composite.new(
-              body_param_defs_array,
-              Apipie::Generator::Swagger::Context.new(
-                allow_null: false,
-                http_method: @current_http_method,
-                controller_method: @current_method
-              )
-            ).to_swagger
-        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|
-        header_hash = {
-          name: header[:name],
-          in: 'header',
-          required: header[:options][:required],
-          description: header[:description],
-          type:  header[:options][:type] || 'string'
-        }
-        header_hash[:default] = header[:options][:default] if header[:options][:default]
-        header_hash
-      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)
-      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 = Apipie::Generator::Swagger::ParamDescription::Builder.
-            new(desc, in_schema: false, controller_method: @current_method).
-            with_description(language: @current_lang).
-            with_name(prefix: prefix).
-            with_type(with_null: @allow_null).
-            with_in(
-              http_method: @current_http_method,
-              default_in_value: default_value_for_in
-            ).to_swagger
-
-          if param_entry[:required]
-            swagger_params_array.unshift(param_entry)
-          else
-            swagger_params_array.push(param_entry)
-          end
-        end
-      end
-    end
-
   end
-
 end

data/lib/apipie/validator.rb

@@ -472,13 +472,13 @@ module Apipie
       end
 
       def self.build(param_description, argument, options, block)
-        if argument == :bool || argument == :boolean
+        if argument == :bool || argument == :boolean || boolean_array?(argument)
           self.new(param_description)
         end
       end
 
-      def expected_type
-        'boolean'
+      private_class_method def self.boolean_array?(argument)
+        argument.is_a?(Array) && (argument - [true, false]) == []
       end
 
       def description
@@ -489,6 +489,10 @@ module Apipie
       def ignore_allow_blank?
         true
       end
+
+      def expected_type
+        'boolean'
+      end
     end
 
     class NestedValidator < BaseValidator

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = "0.9.4"
+  VERSION = "1.0.0"
 end

data/lib/apipie-rails.rb

@@ -8,6 +8,7 @@ require "apipie/routing"
 require "apipie/markup"
 require "apipie/apipie_module"
 require "apipie/dsl_definition"
+require "apipie/generator/swagger/config"
 require "apipie/configuration"
 require "apipie/method_description"
 require "apipie/resource_description"
@@ -27,17 +28,33 @@ require 'apipie/extractor'
 require "apipie/version"
 require "apipie/swagger_generator"
 require "apipie/generator/generator"
+require "apipie/generator/config"
 require "apipie/generator/swagger/swagger"
+require "apipie/generator/swagger/schema"
 require "apipie/generator/swagger/operation_id"
 require "apipie/generator/swagger/warning"
 require "apipie/generator/swagger/warning_writer"
 require "apipie/generator/swagger/type"
 require "apipie/generator/swagger/type_extractor"
 require "apipie/generator/swagger/context"
+require "apipie/generator/swagger/computed_interface_id"
+require "apipie/generator/swagger/path_decorator"
+require "apipie/generator/swagger/referenced_definitions"
+require "apipie/generator/swagger/resource_description_composite"
+require "apipie/generator/swagger/resource_description_collection"
+require "apipie/generator/swagger/method_description"
+require "apipie/generator/swagger/method_description/parameters_service"
+require "apipie/generator/swagger/method_description/response_service"
+require "apipie/generator/swagger/method_description/response_schema_service"
+require "apipie/generator/swagger/method_description/decorator"
+require "apipie/generator/swagger/method_description/api_decorator"
+require "apipie/generator/swagger/method_description/api_schema_service"
 require "apipie/generator/swagger/param_description"
 require "apipie/generator/swagger/param_description/builder"
 require "apipie/generator/swagger/param_description/composite"
 require "apipie/generator/swagger/param_description/description"
 require "apipie/generator/swagger/param_description/in"
 require "apipie/generator/swagger/param_description/name"
+require "apipie/generator/swagger/param_description/path_params_composite"
+require "apipie/generator/swagger/param_description/referenced_composite"
 require "apipie/generator/swagger/param_description/type"