apipie-rails 0.5.19 → 1.3.0

data/lib/apipie/generator/swagger/param_description/builder.rb

@@ -0,0 +1,114 @@
+class Apipie::Generator::Swagger::ParamDescription::Builder
+  # @param [Apipie::ParamDescription] param_description
+  # @param [TrueClass, FalseClass] in_schema
+  # @param [Apipie::MethodDescription] controller_method
+  def initialize(param_description, in_schema:, controller_method:)
+    @param_description = param_description
+    @in_schema = in_schema
+    @controller_method = controller_method
+  end
+
+  # @param [String, nil] prefix
+  def with_name(prefix: nil)
+    @name = Apipie::Generator::Swagger::ParamDescription::Name.
+      new(@param_description, prefixed_by: prefix)
+
+    self
+  end
+
+  # @param [String] language
+  def with_description(language:)
+    @description = Apipie::Generator::Swagger::ParamDescription::Description.
+      new(@param_description, language: language)
+
+    self
+  end
+
+  # @param [TrueClass, FalseClass] with_null
+  def with_type(with_null:)
+    @type = Apipie::Generator::Swagger::ParamDescription::Type.
+      new(@param_description, with_null: with_null, controller_method: @controller_method)
+
+    self
+  end
+
+  def with_in(http_method:, default_in_value: nil)
+    @in = Apipie::Generator::Swagger::ParamDescription::In.new(
+      @param_description,
+      in_schema: @in_schema,
+      default_in_value: default_in_value,
+      http_method: http_method
+    )
+
+    self
+  end
+
+  # @return [Hash]
+  def to_swagger
+    definition = {}
+
+    definition.merge!(@name.to_hash) if @name.present?
+    definition.merge!(@type.to_hash) if @type.present?
+    definition.merge!(@in.to_hash) if @in.present?
+
+    definition.merge!(for_default)
+    definition.merge!(for_required)
+    definition.merge!(for_example)
+    definition.merge!(@description.to_hash) if @description.present?
+
+    warn_optional_without_default_value(definition)
+
+    definition
+  end
+
+  private
+
+  def for_required
+    return {} if !required?
+
+    {
+      required: true
+    }
+  end
+
+  def for_default
+    return {} unless @param_description.options.key?(:default_value)
+
+    {
+      default: @param_description.options[:default_value],
+    }
+  end
+
+  def for_example
+    return {} unless @param_description.options.key?(:example)
+
+    {
+      example: @param_description.options[:example],
+    }
+  end
+
+  def required?
+    required_from_path? || @param_description.required
+  end
+
+  def required_from_path?
+    @param_description.options[:added_from_path] == true
+  end
+
+  def warn_optional_without_default_value(definition)
+    if !required? && !definition.key?(:default)
+      method_id =
+        if @param_description.is_a?(Apipie::ResponseDescriptionAdapter::PropDesc)
+          @controller_method
+        else
+          Apipie::Generator::Swagger::MethodDescription::Decorator.new(@controller_method).ruby_name
+        end
+
+      Apipie::Generator::Swagger::Warning.for_code(
+        Apipie::Generator::Swagger::Warning::OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
+        method_id,
+        { parameter: @param_description.name }
+      ).warn_through_writer
+    end
+  end
+end

data/lib/apipie/generator/swagger/param_description/composite.rb

@@ -0,0 +1,119 @@
+class Apipie::Generator::Swagger::ParamDescription::Composite
+  # @param [Array<Apipie::ParamDescription>] param_descriptions
+  # @param [Apipie::Generator::Swagger::Context] context
+  def initialize(param_descriptions, context)
+    @param_descriptions = param_descriptions
+    @context = context
+    @schema = {
+      type: 'object',
+      properties: {}
+    }
+    @required_params = []
+  end
+
+  def to_swagger
+    return if @param_descriptions.blank?
+
+    @param_descriptions.each do |param_description|
+      validate(param_description)
+
+      if param_description.required
+        @required_params.push(param_description.name.to_sym)
+      end
+
+      param_type = Apipie::Generator::Swagger::TypeExtractor.
+        new(param_description.validator).
+        extract
+
+      has_nested_params = param_type == 'object' &&
+        param_description.validator.params_ordered.present?
+
+      if has_nested_params
+        schema = Apipie::Generator::Swagger::ParamDescription::Composite.new(
+          param_description.validator.params_ordered,
+          Apipie::Generator::Swagger::Context.new(
+            allow_null: @context.allow_null?,
+            http_method: @context.http_method,
+            controller_method: @context.controller_method
+          )
+        ).to_swagger
+
+        return if schema.blank?
+
+        if param_description.additional_properties
+          schema[:additionalProperties] = true
+        end
+
+        if param_description.is_array?
+          schema = for_array(schema)
+        end
+
+        if @context.allow_null?
+          schema = with_null(schema)
+        end
+
+        if schema.present?
+          @schema[:properties][param_description.name.to_sym] = schema
+        end
+      else
+        param_entry = Apipie::Generator::Swagger::ParamDescription::Builder.
+          new(
+            param_description,
+            in_schema: @context.in_schema?,
+            controller_method: @context.controller_method
+          ).
+          with_description(language: @context.language).
+          with_type(with_null: @context.allow_null?).
+          with_in(
+            default_in_value: @context.default_in_value,
+            http_method: @context.http_method
+          ).
+          to_swagger
+
+        @schema[:properties][param_description.name.to_sym] = param_entry
+      end
+    end
+
+    if !Apipie.configuration.generator.swagger.allow_additional_properties_in_response
+      @schema[:additionalProperties] = false
+    end
+
+    if @required_params.length > 0
+      @schema[:required] = @required_params
+    end
+
+    @schema
+  end
+
+  # @param [Symbol, String] param_type
+  #
+  # @return [Apipie::Generator::Swagger::ParamDescription::ReferencedComposite]
+  def referenced(param_type)
+    Apipie::Generator::Swagger::ParamDescription::ReferencedComposite.
+      new(self, param_type)
+  end
+
+  private
+
+  def for_array(schema)
+    {
+      type: 'array',
+      items: schema
+    }
+  end
+
+  def with_null(schema)
+    # 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
+    {
+      anyOf: [ schema, { type: 'null' } ]
+    }
+  end
+
+  def validate(param_description)
+    if !param_description.respond_to?(:required)
+      raise "Unexpected param_desc format"
+    end
+  end
+end

data/lib/apipie/generator/swagger/param_description/description.rb

@@ -0,0 +1,15 @@
+class Apipie::Generator::Swagger::ParamDescription::Description
+  def initialize(param_description, language:)
+    @param_description = param_description
+    @language = language
+  end
+
+  # @return [Hash]
+  def to_hash
+    description = @param_description.options[:desc]
+
+    return {} if description.blank?
+
+    { description: Apipie.app.translate(description, @language) }
+  end
+end

data/lib/apipie/generator/swagger/param_description/in.rb

@@ -0,0 +1,37 @@
+class Apipie::Generator::Swagger::ParamDescription::In
+  IN_KEYWORD_DEFAULT_VALUES = {
+    form_data: 'formData',
+    query: 'query'
+  }
+
+  def initialize(param_description, in_schema:, default_in_value:, http_method:)
+    @param_description = param_description
+    @in_schema = in_schema
+    @default_in_value = default_in_value
+    @http_method = http_method
+  end
+
+  # @return [Hash]
+  def to_hash
+    # The "name" and "in" keys can only be set on root parameters (non-nested)
+    return {} if @in_schema
+
+    { in: in_value }
+  end
+
+  private
+
+  def in_value
+    return @default_in_value if @default_in_value.present?
+
+    if body_allowed_for_current_method?
+      IN_KEYWORD_DEFAULT_VALUES[:form_data]
+    else
+      IN_KEYWORD_DEFAULT_VALUES[:query]
+    end
+  end
+
+  def body_allowed_for_current_method?
+    %w[get head].exclude?(@http_method)
+  end
+end

data/lib/apipie/generator/swagger/param_description/name.rb

@@ -0,0 +1,18 @@
+class Apipie::Generator::Swagger::ParamDescription::Name
+def initialize(param_description, prefixed_by: nil)
+    @param_description = param_description
+    @prefixed_by = prefixed_by
+  end
+
+  # @return [Hash]
+  def to_hash
+    name =
+      if @prefixed_by.present?
+        "#{@prefixed_by}[#{@param_description.name}]"
+      else
+        @param_description.name
+      end
+
+    { name: name }
+  end
+end

data/lib/apipie/generator/swagger/param_description/path_params_composite.rb

@@ -0,0 +1,61 @@
+class Apipie::Generator::Swagger::ParamDescription::PathParamsComposite
+  # @param [Array<Apipie::ParamDescription>] param_descriptions
+  # @param [Apipie::Generator::Swagger::Context] context
+  def initialize(param_descriptions, context)
+    @param_descriptions = param_descriptions
+    @context = context
+    @result = []
+  end
+
+  # @return [Array]
+  def to_swagger
+    @param_descriptions.each do |desc|
+      context = @context.dup
+
+      type = Apipie::Generator::Swagger::TypeExtractor.new(desc.validator).extract
+
+      if type == 'object' && desc.validator.params_ordered.blank?
+        warn_param_ignored_in_form_data(desc.name)
+        next
+      end
+
+      has_nested_params = type == 'object' &&
+                          desc.validator.params_ordered.present?
+
+      if has_nested_params
+        context.add_to_prefix!(desc.name)
+
+        out = Apipie::Generator::Swagger::ParamDescription::PathParamsComposite
+              .new(desc.validator.params_ordered, context)
+              .to_swagger
+
+        @result.concat(out)
+      else
+        param_entry =
+          Apipie::Generator::Swagger::ParamDescription::Builder
+          .new(desc, in_schema: false, controller_method: context.controller_method)
+          .with_description(language: context.language)
+          .with_name(prefix: context.prefix)
+          .with_type(with_null: context.allow_null?)
+          .with_in(
+            http_method: context.http_method,
+            default_in_value: context.default_in_value
+          ).to_swagger
+
+        @result << param_entry
+      end
+    end
+
+    @result.sort_by { |p| p[:required] ? 0 : 1 }
+  end
+
+  private
+
+  def warn_param_ignored_in_form_data(name)
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::PARAM_IGNORED_IN_FORM_DATA_CODE,
+      @context.controller_method.ruby_name,
+      { parameter: name }
+    ).warn_through_writer
+  end
+end

data/lib/apipie/generator/swagger/param_description/referenced_composite.rb

@@ -0,0 +1,36 @@
+# A Composite that keeps track when a param description has been added to references
+#   and returns the reference instead of the complete object
+class Apipie::Generator::Swagger::ParamDescription::ReferencedComposite
+  # @param [Apipie::Generator::Swagger::ParamDescription::Composite] composite
+  # @param [Symbol, String] param_type
+  def initialize(composite, param_type)
+    @composite = composite
+    @param_type = param_type.to_sym
+  end
+
+  def to_swagger
+    return ref_to(:name) if added?(:name)
+
+    schema_obj = @composite.to_swagger
+
+    return nil if schema_obj.nil?
+
+    add(schema_obj)
+
+    { '$ref' => ref_to(@param_type) }
+  end
+
+  private
+
+  def ref_to(name)
+    "#/definitions/#{name}"
+  end
+
+  def add(schema)
+    Apipie::Generator::Swagger::ReferencedDefinitions.instance.add!(@param_type, schema)
+  end
+
+  def added?(name)
+    Apipie::Generator::Swagger::ReferencedDefinitions.instance.added?(name)
+  end
+end

data/lib/apipie/generator/swagger/param_description/type.rb

@@ -0,0 +1,128 @@
+class Apipie::Generator::Swagger::ParamDescription::Type
+  def initialize(param_description, with_null:, controller_method:)
+    @param_description = param_description
+    @with_null = with_null
+    @controller_method = controller_method
+  end
+
+  # @return [Hash]
+  def to_hash
+    type_definition = {}
+
+    case type.to_s
+    when 'array'
+      type_definition.merge!(for_array_type)
+    when 'enum'
+      type_definition.merge!(for_enum_type)
+    when 'object'
+      # We only get here if there is no specification
+      # of properties for this object.
+      type_definition.merge!(for_object_type)
+      warn_hash_without_internal_typespec
+    else
+      type_definition.merge!({ type: type.to_s })
+    end
+
+    if @param_description.is_array?
+      type_definition = {
+        items: type_definition,
+        type: 'array'
+      }
+
+      if @with_null
+        type_definition[:type] = [type_definition[:type], 'null']
+      end
+    end
+
+    if @with_null
+      type_definition[:type] = [type_definition[:type], 'null']
+    end
+
+    type_definition
+  end
+
+  private
+
+  def params_in_body_use_reference?
+    Apipie.configuration.generator.swagger.json_input_uses_refs
+  end
+
+  # @return [Apipie::Generator::Swagger::Type, String]
+  def type
+    @_type ||= Apipie::Generator::Swagger::TypeExtractor.
+      new(validator).
+      extract
+  end
+
+  def for_array_type
+    validator_opts = validator.param_description.options
+    items_type = (validator_opts[:of] || validator_opts[:array_of]).to_s
+
+    if items_type == 'Hash' && params_in_body_use_reference?
+      reference_name = Apipie::Generator::Swagger::OperationId.
+        from(@param_description.method_description, param: @param_description.name).
+        to_s
+
+      items = {
+        '$ref' => reference_name
+      }
+    else
+      items = { type: array_items_type(items_type).to_s }
+    end
+
+    enum = @param_description.options[:in]
+
+    items[:enum] = enum if enum.present?
+
+    {
+      type: 'array',
+      items: items
+    }
+  end
+
+  # @param [String] items_type
+  #
+  # @return [Apipie::Generator::Swagger::Type]
+  def array_items_type(items_type)
+    type = Apipie::Generator::Swagger::TypeExtractor::TYPES[items_type.downcase.to_sym]
+
+    if type == 'object' || type.blank?
+      Apipie::Generator::Swagger::TypeExtractor::TYPES[:string]
+    else
+      type
+    end
+  end
+
+  def for_enum_type
+    {
+      type: 'string',
+      enum: @param_description.validator.values
+    }
+  end
+
+  def for_object_type
+    {
+      type: 'object',
+      additionalProperties: true
+    }
+  end
+
+  def validator
+    @_validator ||= @param_description.validator
+  end
+
+  def warn_hash_without_internal_typespec
+    method_id =
+      if @param_description.is_a?(Apipie::ResponseDescriptionAdapter::PropDesc)
+        @controller_method.method
+      else
+        Apipie::Generator::Swagger::MethodDescription::Decorator.new(@param_description.method_description).ruby_name
+      end
+
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
+      method_id,
+      { parameter: @param_description.name }
+    ).warn_through_writer
+  end
+end

data/lib/apipie/generator/swagger/param_description.rb

@@ -0,0 +1,18 @@
+module Apipie::Generator::Swagger::ParamDescription
+  # @param [Apipie::MethodDescription] method_description
+  # @param [String] name
+  #
+  # @return [Apipie::ParamDescription]
+  def self.create_for_missing_param(method_description, name)
+    Apipie::ParamDescription.new(
+      method_description,
+      name,
+      Numeric,
+      {
+        in: "path",
+        required: true,
+        added_from_path: true,
+      }
+    )
+  end
+end

data/lib/apipie/generator/swagger/path_decorator.rb

@@ -0,0 +1,36 @@
+class Apipie::Generator::Swagger::PathDecorator < SimpleDelegator
+  def param_names
+    @param_names ||= scan(/:(\w+)/).map { |ar| ar[0].to_sym }
+  end
+
+  # @param [Symbol] param_name
+  def param?(param_name)
+    param_names.include?(param_name)
+  end
+
+  # @param [String] controller_method
+  #
+  # @return [Apipie::Generator::Swagger::PathDecorator]
+  def swagger_path(controller_method = nil)
+    current_path = gsub(/:(\w+)/, '{\1}').gsub(%r{/$}, '')
+
+    unless current_path.starts_with?('/')
+      warn_for_missing_slash(controller_method) if controller_method.present?
+
+      current_path = "/#{current_path}"
+    end
+
+    current_path
+  end
+
+  private
+
+  # @param [String] controller_method
+  def warn_for_missing_slash(controller_method)
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::ADDED_MISSING_SLASH_CODE,
+      controller_method,
+      { path: self }
+    ).warn_through_writer
+  end
+end

data/lib/apipie/generator/swagger/referenced_definitions.rb

@@ -0,0 +1,17 @@
+class Apipie::Generator::Swagger::ReferencedDefinitions
+  include Singleton
+
+  attr_reader :definitions
+
+  def initialize
+    @definitions = {}
+  end
+
+  def add!(param_type, schema)
+    @definitions[param_type] = schema
+  end
+
+  def added?(name)
+    @definitions.key?(name)
+  end
+end

data/lib/apipie/generator/swagger/resource_description_collection.rb

@@ -0,0 +1,30 @@
+class Apipie::Generator::Swagger::ResourceDescriptionsCollection
+  # @param [Hash{String->Apipie::ResourceDescription}] resource_descriptions
+  def initialize(resource_descriptions)
+    @resource_descriptions = resource_descriptions
+  end
+
+  # @return [Array<Apipie::ResourceDescription>]
+  def filter(version:, resource_id:, method_name: nil)
+    resources = []
+
+    # If resource_id 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
+    @resource_descriptions[version].each do |resource_description_id, resource_description|
+      if (resource_id.blank? && resource_description._methods.present?) || resource_description_id == resource_id
+        resources << resource_description
+      end
+    end
+
+    if method_name.present?
+      resources = resources.select do |resource_description|
+        resource_description._methods.any? do |method_description_name, _|
+          method_description_name == method_name
+        end
+      end
+    end
+
+    resources
+  end
+end

data/lib/apipie/generator/swagger/resource_description_composite.rb

@@ -0,0 +1,56 @@
+class Apipie::Generator::Swagger::ResourceDescriptionComposite
+  # @param [Array<Apipie::ResourceDescription>] resource_descriptions
+  def initialize(resource_descriptions, language:)
+    @resource_descriptions = resource_descriptions
+    @language = language
+  end
+
+  # @return [Hash{Symbol->Array | Hash}]
+  def to_swagger
+    {
+      tags: tags,
+      paths: paths
+    }
+  end
+
+  # @return [Array]
+  def tags
+    results = []
+
+    @resource_descriptions.each do |resource_description|
+      next unless resource_description._full_description
+
+      results << {
+        name: resource_description._id,
+        description: Apipie.app.translate(
+          resource_description._full_description,
+          @language
+        )
+      }
+    end
+
+    results
+  end
+
+  # @return [Hash]
+  def paths
+    results = {}
+
+    @resource_descriptions.each do |resource_description|
+      resource_description._methods.each_value do |method_description|
+        next unless method_description.show
+
+        result = Apipie::Generator::Swagger::MethodDescription::ApiSchemaService
+                 .new(
+                   Apipie::Generator::Swagger::MethodDescription::Decorator.new(method_description),
+                   language: @language
+                 )
+                 .call
+
+        results.deep_merge!(result)
+      end
+    end
+
+    results
+  end
+end