apipie-dsl 2.0.0

data/lib/apipie_dsl/errors.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class Error < StandardError; end
+  class ParamError < Error
+    attr_accessor :param
+
+    def initialize(param)
+      @param = param
+    end
+  end
+
+  class ParamMissing < ParamError
+    def to_s
+      return "Missing parameter #{@param.name}" if @param.options[:missing_message].nil?
+
+      if @param.options[:missing_message].is_a?(Proc)
+        @param.options[:missing_message].call
+      else
+        @param.options[:missing_message].to_s
+      end
+    end
+  end
+
+  class UnknownParam < ParamError
+    def to_s
+      "Unknown parameter #{@param}"
+    end
+  end
+
+  class ParamInvalid < ParamError
+    attr_accessor :value, :error
+
+    def initialize(param, value, error)
+      super(param)
+      @value = value
+      @error = error
+    end
+
+    def to_s
+      "Invalid parameter '#{@param}' value #{@value.inspect}: #{@error}"
+    end
+  end
+
+  class MultipleDefinitionError < Error
+    attr_accessor :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_s
+      "Multiple definition of #{@value}"
+    end
+  end
+
+  class ReturnsMultipleDefinitionError < Error
+    def to_s
+      "A 'returns' statement cannot indicate both array_of and type"
+    end
+  end
+
+  class MultipleReturnsError < Error
+    def to_s
+      "A 'returns' statement cannot be used more than once"
+    end
+  end
+end

data/lib/apipie_dsl/exception_description.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class ExceptionDescription
+    attr_reader :error, :description, :metadata
+
+    def self.from_dsl_data(args)
+      error_or_options, desc, options = args
+      ApipieDSL::ExceptionDescription.new(error_or_options, desc, options)
+    end
+
+    def initialize(error_or_options, desc = nil, options = {})
+      if error_or_options.is_a?(Hash)
+        error_or_options = error_or_options.transform_keys(&:to_sym)
+        @error = error_or_options[:error]
+        @metadata = error_or_options[:meta]
+        @description = error_or_options[:desc] || error_or_options[:description]
+      else
+        @error = if error_or_options.is_a?(Symbol)
+                   Rack::Utils::SYMBOL_TO_STATUS_CODE[error_or_options]
+                 else
+                   error_or_options
+                 end
+        raise ArgumentError, error_or_options unless @error
+
+        @metadata = options[:meta]
+        @description = desc
+      end
+    end
+
+    def docs
+      {
+        error: error,
+        description: ApipieDSL.markup_to_html(description),
+        metadata: metadata
+      }
+    end
+  end
+end

data/lib/apipie_dsl/markup.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  module Markup
+    class RDoc
+      def initialize
+        require 'rdoc'
+        require 'rdoc/markup/to_html'
+        @rdoc ||= 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
+
+      def to_html(text)
+        @rdoc.convert(text)
+      end
+    end
+
+    class Markdown
+      def initialize
+        require 'maruku'
+      end
+
+      def to_html(text)
+        Maruku.new(text).to_html
+      end
+    end
+
+    class Textile
+      def initialize
+        require 'RedCloth'
+      end
+
+      def to_html(text)
+        RedCloth.new(text).to_html
+      end
+    end
+  end
+end

data/lib/apipie_dsl/method_description.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class MethodDescription
+    attr_reader :name, :klass, :see, :examples
+    attr_accessor :full_description, :short_description, :metadata, :show,
+                  :raises, :returns, :aliases
+    alias_method :class_description, :klass
+
+    def self.from_dsl_data(klass, args)
+      name, dsl_data = args
+      ApipieDSL::MethodDescription.new(name, klass, dsl_data)
+    end
+
+    def initialize(name, klass, dsl_data)
+      @name = name.to_s
+      @klass = klass
+
+      desc = dsl_data[:description] || ''
+      @full_description = ApipieDSL.markup_to_html(desc)
+
+      @short_description = dsl_data[:short_description] || ''
+
+      @params = (dsl_data[:params] || []).map do |args|
+        ApipieDSL::ParameterDescription.from_dsl_data(self, args)
+      end
+
+      @params = ApipieDSL::ParameterDescription.unify(@params)
+
+      @raises = (dsl_data[:raises] || []).map do |args|
+        ApipieDSL::ExceptionDescription.from_dsl_data(args)
+      end
+
+      # Every method in Ruby returns an onject
+      dsl_data[:returns] = [{ object_of: Object }] if dsl_data[:returns].nil?
+
+      @returns = ApipieDSL::ReturnDescription.from_dsl_data(self, dsl_data[:returns])
+
+      @tag_list = dsl_data[:tag_list]
+
+      @see = (dsl_data[:see] || []).map do |method, options|
+        options[:scope] ||= @klass
+        ApipieDSL::SeeDescription.new(method, options)
+      end
+
+      @metadata = dsl_data[:meta]
+
+      @show = dsl_data[:show].nil? ? true : dsl_data[:show]
+
+      @examples = (dsl_data[:examples] || []).select do |example|
+        next example if example[:for].nil?
+
+        example[:for].to_s == @name
+      end
+
+      @aliases = dsl_data[:aliases]
+    end
+
+    def id
+      "#{klass.id}##{name}"
+    end
+
+    def plain_params
+      @params
+    end
+
+    def params
+      param_descriptions.each_with_object({}) { |p, h| h[p.name] = p }
+                        .sort.to_h
+    end
+
+    def param_descriptions
+      @params.select(&:validator)
+    end
+
+    def tag_list
+      parent = ApipieDSL.get_class_description(ApipieDSL.superclass_for(@klass.class))
+      parent_tags = [parent, @klass].compact.flat_map(&:tag_list_arg)
+      ApipieDSL::TagListDescription.new((parent_tags + @tag_list).uniq.compact)
+    end
+
+    def version
+      klass.version
+    end
+
+    def doc_url(section = nil)
+      crumbs = []
+      crumbs << @klass.version if ApipieDSL.configuration.version_in_url
+      crumbs << section if section
+      crumbs << @klass.id
+      crumbs << @name
+      ApipieDSL.full_url(crumbs.join('/')).gsub('?', '%3F')
+    end
+
+    def docs(section = nil, lang = nil)
+      {
+        doc_url: doc_url(section),
+        name: @name,
+        full_description: ApipieDSL.translate(@full_description, lang),
+        short_description: ApipieDSL.translate(@short_description, lang),
+        params: param_descriptions.map { |param| param.docs(lang) }.flatten,
+        raises: raises.map(&:docs),
+        returns: @returns.docs(lang),
+        metadata: @metadata,
+        see: see.map(&:docs),
+        show: @show,
+        examples: @examples,
+        aliases: aliases
+      }
+    end
+  end
+end

data/lib/apipie_dsl/parameter_description.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  # method parameter description
+  #
+  # name - method name (show)
+  # desc - description
+  # validator - Validator::BaseValidator subclass
+  class ParameterDescription
+    attr_reader :name, :desc, :type, :options, :method_description,
+                :metadata, :show, :is_array, :default_value
+    attr_accessor :parent
+
+    alias_method :is_array?, :is_array
+
+    def self.from_dsl_data(method_description, args)
+      name, validator, desc_or_options, options, block = args
+      ApipieDSL::ParameterDescription.new(method_description,
+                                          name,
+                                          validator,
+                                          desc_or_options,
+                                          options,
+                                          &block)
+    end
+
+    def ==(other)
+      return false unless self.class == other.class
+
+      if method_description == other.method_description && @options == other.options
+        true
+      else
+        false
+      end
+    end
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(method_description, name, validator, desc_or_options = nil, options = {}, &block)
+      if desc_or_options.is_a?(Hash)
+        options = options.merge(desc_or_options)
+      elsif desc_or_options.is_a?(String)
+        options[:desc] = desc_or_options
+      elsif !desc_or_options.nil?
+        raise ArgumentError, 'Parameter description: expected description or options as 3rd parameter'
+      end
+
+      @options = options.transform_keys(&:to_sym)
+
+      @method_description = method_description
+      @name = name
+      @desc = @options[:desc]
+      @type = @options[:type] || :required
+      @schema = @options[:schema]
+      @default_value = @options[:default]
+      @parent = @options[:parent]
+      @metadata = @options[:meta]
+      @show = @options.key?(:show) ? @options[:show] : true
+
+      return unless validator
+
+      @validator = if validator.is_a?(String)
+        ApipieDSL::Validator::Lazy.new(self, validator, @options, block)
+      else
+        ApipieDSL::Validator::BaseValidator.find(self, validator, @options, block)
+      end
+      raise StandardError, "Validator for #{validator} not found." unless @validator
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def validator
+      return @validator unless @validator.is_a?(ApipieDSL::Validator::Lazy)
+
+      @validator = @validator.build
+    end
+
+    def validate(value)
+      validator.valid?(value)
+    end
+
+    def full_name
+      name_parts = parents_and_self.map { |p| p.name if p.show }.compact
+      return name.to_s if name_parts.empty?
+
+      ([name_parts.first] + name_parts[1..-1].map { |n| "[#{n}]" }).join('')
+    end
+
+    # Returns an array of all the parents: starting with the root parent
+    # ending with itself
+    def parents_and_self
+      ret = []
+      ret.concat(parent.parents_and_self) if parent
+      ret << self
+      ret
+    end
+
+    def merge_with(other_param_desc)
+      if validator && other_param_desc.validator
+        validator.merge_with(other_param_desc.validator)
+      else
+        self.validator ||= other_param_desc.validator
+      end
+      self
+    end
+
+    # Merge param descriptions. Allows defining hash params on more places
+    # (e.g. in param_groups). For example:
+    #
+    #     def_param_group :user do
+    #       param :user, Hash do
+    #         param :name, String
+    #       end
+    #     end
+    #
+    #     param_group :user
+    #     param :user, Hash do
+    #       param :password, String
+    #     end
+    def self.unify(params)
+      ordering = params.map(&:name)
+      params.group_by(&:name).map do |_name, description|
+        description.reduce(&:merge_with)
+      end.sort_by { |param| ordering.index(param.name) }
+    end
+
+    def self.merge(target_params, source_params)
+      params_to_merge, params_to_add = source_params.partition do |source_param|
+        target_params.any? { |target_param| source_param.name == target_param.name }
+      end
+      unify(target_params + params_to_merge)
+      target_params.concat(params_to_add)
+    end
+
+    def docs(lang = nil)
+      hash = {
+        name: name.to_s,
+        full_name: full_name,
+        description: ApipieDSL.markup_to_html(ApipieDSL.translate(@options[:desc], lang)),
+        type: type.to_s,
+        default: default_value,
+        validator: validator.to_s,
+        expected_type: validator.expected_type,
+        metadata: metadata,
+        show: show
+      }
+      hash.delete(:default) if type == :required
+      hash[:schema] = @schema if type == :block
+      return hash unless validator.sub_params
+
+      hash[:params] = validator.sub_params.map { |param| param.docs(lang) }
+      hash
+    end
+  end
+end

data/lib/apipie_dsl/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'apipie-dsl'
+require 'rails'
+
+module ApipieDSL
+  class Railtie < Rails::Railtie
+    railtie_name :apipie_dsl
+
+    rake_tasks do
+      path = File.expand_path(__dir__)
+      Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/apipie_dsl/return_description.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class ReturnDescription
+    class ReturnObject
+      include ApipieDSL::Base
+      include ApipieDSL::Parameter
+
+      def initialize(method_description, options, block)
+        @method_description = method_description
+        @scope = options[:scope]
+        @param_group = { scope: @scope }
+        @options = options
+        @return_type = (@options.keys & %i[array_of one_of object_of param_group]).first
+
+        return unless @options[@return_type].is_a?(::Class)
+      end
+
+      # this routine overrides Param#default_param_group_scope
+      # and is called if Param#param_group is invoked
+      # during the instance_exec call in ReturnObject#initialize
+      def default_param_group_scope
+        @scope
+      end
+
+      def return_class
+        case @return_type
+        when :object_of
+          @options[@return_type]
+        when :one_of, :param_group
+          Object
+        when :array_of
+          Array
+        end
+      end
+
+      def docs(lang = nil)
+        {
+          meta: @return_type,
+          class: return_class,
+          data: @options[@return_type]
+        }
+      end
+    end
+  end
+
+  class ReturnDescription
+    def self.from_dsl_data(method_description, args)
+      options, block = args
+
+      new(method_description, options, block)
+    end
+
+    def initialize(method_description, options, block)
+      if options[:array_of] && options[:one_of] && options[:object_of] && options[:param_group]
+        raise ReturnsMultipleDefinitionError, options
+      end
+
+      @description = options[:desc]
+      @returns_object = ReturnObject.new(method_description, options, block)
+    end
+
+
+    def docs(lang = nil)
+      {
+        description: @description,
+        object: @returns_object.docs(lang)
+      }
+    end
+  end
+end