apipie-rails 0.9.1 → 0.9.3

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

@@ -0,0 +1,105 @@
+class Apipie::Generator::Swagger::ParamDescription::Builder
+  # @param [Apipie::ParamDescription] param_description
+  # @param [TrueClass, FalseClass] in_schema
+  # @param [String] 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!(@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 {} if @param_description.options[:default_value].blank?
+
+    {
+      default: @param_description.options[:default_value],
+    }
+  end
+
+  def required?
+    required_from_path? || (!@in_schema && @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 =
+        if @param_description.is_a?(Apipie::ResponseDescriptionAdapter::PropDesc)
+          @controller_method
+        else
+          @param_description.method_description.method
+        end
+
+      Apipie::Generator::Swagger::Warning.for_code(
+        Apipie::Generator::Swagger::Warning::OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
+        method,
+        { parameter: @param_description.name }
+      ).warn_through_writer
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+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.swagger_allow_additional_properties_in_response
+      @schema[:additionalProperties] = false
+    end
+
+    if @required_params.length > 0
+      @schema[:required] = @required_params
+    end
+
+    @schema
+  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?
+    ['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/type.rb

@@ -0,0 +1,108 @@
+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.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].to_s || 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: 'string' }
+    end
+
+    enum = @param_description.options[:in]
+
+    items[:enum] = enum if enum.present?
+
+    {
+      type: 'array',
+      items: items
+    }
+  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
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
+      @controller_method,
+      { 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/type_extractor.rb

@@ -34,8 +34,6 @@ class Apipie::Generator::Swagger::TypeExtractor
     extract
   end
 
-  private
-
   def extract
     expected_type =
       if string?
@@ -51,6 +49,8 @@ class Apipie::Generator::Swagger::TypeExtractor
     TYPES[expected_type] || @validator.expected_type
   end
 
+  private
+
   def string?
     @validator.blank?
   end

data/lib/apipie/markup.rb

@@ -4,6 +4,11 @@ module Apipie
 
     class RDoc
 
+      def initialize
+        require 'rdoc'
+        require 'rdoc/markup/to_html'
+      end
+
       def to_html(text)
         rdoc.convert(text)
       end
@@ -11,14 +16,10 @@ module Apipie
       private
 
       def rdoc
-        @rdoc ||= begin
-          require 'rdoc'
-          require 'rdoc/markup/to_html'
-          if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
-            ::RDoc::Markup::ToHtml.new()
-          else
-            ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
-          end
+        if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
+          ::RDoc::Markup::ToHtml.new()
+        else
+          ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
         end
       end
     end

data/lib/apipie/method_description.rb

@@ -10,8 +10,7 @@ module Apipie
       @from_concern = dsl_data[:from_concern]
       @apis = ApisService.new(resource, method, dsl_data).call
 
-      desc = dsl_data[:description] || ''
-      @full_description = Apipie.markup_to_html(desc)
+      @full_description = dsl_data[:description] || ''
 
       @errors = dsl_data[:errors].map do |args|
         Apipie::ErrorDescription.from_dsl_data(args)
@@ -40,7 +39,7 @@ module Apipie
       @params_ordered = ParamDescription.unify(@params_ordered)
       @headers = dsl_data[:headers]
 
-      @show = if dsl_data.has_key? :show
+      @show = if dsl_data.key? :show
         dsl_data[:show]
       else
         true
@@ -166,8 +165,8 @@ module Apipie
         :name => @method,
         :apis => method_apis_to_json(lang),
         :formats => formats,
-        :full_description => Apipie.app.translate(@full_description, lang),
-        :errors => errors.map(&:to_json),
+        :full_description => Apipie.markup_to_html(Apipie.app.translate(@full_description, lang)),
+        :errors => errors.map{ |error| error.to_json(lang) }.flatten,
         :params => params_ordered.map{ |param| param.to_json(lang) }.flatten,
         :returns => @returns.map{ |return_item| return_item.to_json(lang) }.flatten,
         :examples => @examples,

data/lib/apipie/param_description/deprecation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Apipie
+  class ParamDescription
+    # Data transfer object, used when param description is deprecated
+    class Deprecation
+      attr_reader :info, :deprecated_in, :sunset_at
+
+      def initialize(info: nil, deprecated_in: nil, sunset_at: nil)
+        @info = info
+        @deprecated_in = deprecated_in
+        @sunset_at = sunset_at
+      end
+
+      def to_json(*_args)
+        {
+          info: @info,
+          deprecated_in: @deprecated_in,
+          sunset_at: @sunset_at
+        }
+      end
+    end
+  end
+end

data/lib/apipie/param_description.rb

@@ -12,9 +12,9 @@ module Apipie
     attr_reader :additional_properties, :is_array
     attr_accessor :parent, :required
 
-    alias_method :response_only?, :response_only
-    alias_method :request_only?, :request_only
-    alias_method :is_array?, :is_array
+    alias response_only? response_only
+    alias request_only? request_only
+    alias is_array? is_array
 
     def self.from_dsl_data(method_description, args)
       param_name, validator, desc_or_options, options, block = args
@@ -71,7 +71,7 @@ module Apipie
       @request_only = (@options[:only_in] == :request)
       raise ArgumentError.new("'#{@options[:only_in]}' is not a valid value for :only_in") if (!@response_only && !@request_only) && @options[:only_in].present?
 
-      @show = if @options.has_key? :show
+      @show = if @options.key? :show
         @options[:show]
       else
         true
@@ -97,6 +97,7 @@ module Apipie
       @validations = Array(options[:validations]).map {|v| concern_subst(Apipie.markup_to_html(v)) }
 
       @additional_properties = @options[:additional_properties]
+      @deprecated = @options[:deprecated] || false
     end
 
     def from_concern?
@@ -155,17 +156,25 @@ module Apipie
     end
 
     def to_json(lang = nil)
-      hash = { :name => name.to_s,
-               :full_name => full_name,
-               :description => preformat_text(Apipie.app.translate(@options[:desc], lang)),
-               :required => required,
-               :allow_nil => allow_nil,
-               :allow_blank => allow_blank,
-               :validator => validator.to_s,
-               :expected_type => validator.expected_type,
-               :metadata => metadata,
-               :show => show,
-               :validations => validations }
+      hash = {
+        name: name.to_s,
+        full_name: full_name,
+        description: preformat_text(Apipie.app.translate(@options[:desc], lang)),
+        required: required,
+        allow_nil: allow_nil,
+        allow_blank: allow_blank,
+        validator: validator.to_s,
+        expected_type: validator.expected_type,
+        metadata: metadata,
+        show: show,
+        validations: validations,
+        deprecated: deprecated?
+      }
+
+      if deprecation.present?
+        hash[:deprecation] = deprecation.to_json
+      end
+
       if sub_params = validator.params_ordered
         hash[:params] = sub_params.map { |p| p.to_json(lang)}
       end
@@ -212,7 +221,7 @@ module Apipie
     # action awareness is being inherited from ancestors (in terms of
     # nested params)
     def action_aware?
-      if @options.has_key?(:action_aware)
+      if @options.key?(:action_aware)
         return @options[:action_aware]
       elsif @parent
         @parent.action_aware?
@@ -237,7 +246,7 @@ module Apipie
     # crate/update actions.
     def action_awareness
       if action_aware?
-        if !@options.has_key?(:allow_nil)
+        if !@options.key?(:allow_nil)
           if @required
             @allow_nil = false
           else
@@ -268,7 +277,7 @@ module Apipie
     end
 
     def is_required?
-      if @options.has_key?(:required)
+      if @options.key?(:required)
         if (@options[:required] == true) || (@options[:required] == false)
           @options[:required]
         else
@@ -279,6 +288,24 @@ module Apipie
       end
     end
 
+    def deprecated?
+      @deprecated.present?
+    end
+
+    def deprecation
+      return if @deprecated.blank? || @deprecated == true
+
+      case @deprecated
+      when Hash
+        Apipie::ParamDescription::Deprecation.new(
+          info: @deprecated[:info],
+          deprecated_in: @deprecated[:in],
+          sunset_at: @deprecated[:sunset]
+        )
+      when String
+        Apipie::ParamDescription::Deprecation.new(info: @deprecated)
+      end
+    end
   end
 
 end

data/lib/apipie/resource_description.rb

@@ -17,7 +17,7 @@ module Apipie
       :_path, :_name, :_params_args, :_returns_args, :_tag_list_arg, :_errors_args,
       :_formats, :_parent, :_metadata, :_headers, :_deprecated
 
-    def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
+    def initialize(controller, resource_name, dsl_data = nil, version = nil)
 
       @_methods = ActiveSupport::OrderedHash.new
       @_params_args = []
@@ -35,7 +35,7 @@ module Apipie
 
     def update_from_dsl_data(dsl_data)
       @_name = dsl_data[:resource_name] if dsl_data[:resource_name]
-      @_full_description = Apipie.markup_to_html(dsl_data[:description])
+      @_full_description = dsl_data[:description]
       @_short_description = dsl_data[:short_description]
       @_path = dsl_data[:path] || ""
       @_formats = dsl_data[:formats]
@@ -71,7 +71,7 @@ module Apipie
     end
 
     def remove_method_description(method_name)
-      if @_methods.has_key?(method_name)
+      if @_methods.key?(method_name)
         @_methods.delete(method_name)
       end
     end
@@ -110,7 +110,7 @@ module Apipie
         :api_url => api_url,
         :name => @_name,
         :short_description => Apipie.app.translate(@_short_description, lang),
-        :full_description => Apipie.app.translate(@_full_description, lang),
+        :full_description => Apipie.markup_to_html(Apipie.app.translate(@_full_description, lang)),
         :version => _version,
         :formats => @_formats,
         :metadata => @_metadata,

data/lib/apipie/response_description.rb

@@ -116,12 +116,12 @@ module Apipie
     def additional_properties
       !!@response_object.additional_properties
     end
-    alias :allow_additional_properties :additional_properties
+    alias allow_additional_properties additional_properties
 
     def to_json(lang=nil)
       {
           :code => code,
-          :description => description,
+          :description => Apipie.app.translate(description, lang),
           :is_array => is_array?,
           :returns_object => params_ordered.map{ |param| param.to_json(lang).tap{|h| h.delete(:validations) }}.flatten,
           :additional_properties => additional_properties,