apipie-rails-jq 1.4.3.pre.beta.pre.jq.1

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

@@ -0,0 +1,51 @@
+class Apipie::Generator::Swagger::TypeExtractor
+  TYPES = {
+    numeric: 'number',
+    hash: 'object',
+    array: 'array',
+    enum: 'enum',
+
+    # see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
+    integer: Apipie::Generator::Swagger::Type.new('integer', 'int32'),
+    long: Apipie::Generator::Swagger::Type.new('integer', 'int64'),
+    number: Apipie::Generator::Swagger::Type.new('number'),
+    float: Apipie::Generator::Swagger::Type.new('number', 'float'),
+    double: Apipie::Generator::Swagger::Type.new('number', 'double'),
+    string: Apipie::Generator::Swagger::Type.new('string'),
+    byte: Apipie::Generator::Swagger::Type.new('string', 'byte'),
+    binary: Apipie::Generator::Swagger::Type.new('string', 'binary'),
+    boolean: Apipie::Generator::Swagger::Type.new('boolean'),
+    date: Apipie::Generator::Swagger::Type.new('string', 'date'),
+    dateTime: Apipie::Generator::Swagger::Type.new('string', 'date-time'),
+    password: Apipie::Generator::Swagger::Type.new('string', 'password')
+  }.freeze
+
+  # @param [Apipie::Validator::BaseValidator, ResponseDescriptionAdapter::PropDesc::Validator, nil] validator
+  def initialize(validator)
+    @validator = validator
+  end
+
+  def extract
+    expected_type =
+      if string?
+        :string
+      elsif enum?
+        :enum
+      else
+        @validator.expected_type.to_sym
+      end
+
+    TYPES[expected_type] || @validator.expected_type
+  end
+
+  private
+
+  def string?
+    @validator.blank?
+  end
+
+  def enum?
+    @validator.is_a?(Apipie::Validator::EnumValidator) ||
+      (@validator.respond_to?(:is_enum?) && @validator.is_enum?)
+  end
+end

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

@@ -0,0 +1,74 @@
+class Apipie::Generator::Swagger::Warning
+  MISSING_METHOD_SUMMARY_CODE = 100
+  ADDED_MISSING_SLASH_CODE = 101
+  NO_RETURN_CODES_SPECIFIED_CODE = 102
+  HASH_WITHOUT_INTERNAL_TYPESPEC_CODE = 103
+  OPTIONAL_PARAM_IN_PATH_CODE = 104
+  OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE = 105
+  PARAM_IGNORED_IN_FORM_DATA_CODE = 106
+  PATH_PARAM_NOT_DESCRIBED_CODE = 107
+
+  CODES = {
+    missing_method_summary: MISSING_METHOD_SUMMARY_CODE,
+    added_missing_slash: ADDED_MISSING_SLASH_CODE,
+    no_return_codes_specified: NO_RETURN_CODES_SPECIFIED_CODE,
+    hash_without_internal_typespec: HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
+    optional_param_in_path: OPTIONAL_PARAM_IN_PATH_CODE,
+    optional_without_default_value: OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
+    param_ignored_in_form_data: PARAM_IGNORED_IN_FORM_DATA_CODE,
+    path_param_not_described_code: PATH_PARAM_NOT_DESCRIBED_CODE
+  }.freeze
+
+  MESSAGES = {
+    MISSING_METHOD_SUMMARY_CODE => "Missing short description for method",
+    ADDED_MISSING_SLASH_CODE => "Added missing / at beginning of path: %{path}",
+    HASH_WITHOUT_INTERNAL_TYPESPEC_CODE => "The parameter :%{parameter} is a generic Hash without an internal type specification",
+    NO_RETURN_CODES_SPECIFIED_CODE => "No return codes ('errors') specified",
+    OPTIONAL_PARAM_IN_PATH_CODE => "The parameter :%{parameter} is 'in-path'.  Ignoring 'not required' in DSL",
+    OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE => "The parameter :%{parameter} is optional but default value is not specified (use :default_value => ...)",
+    PARAM_IGNORED_IN_FORM_DATA_CODE => "Ignoring param :%{parameter} -- cannot include Hash without fields in a formData specification",
+    PATH_PARAM_NOT_DESCRIBED_CODE => "The parameter :%{name} appears in the path %{path} but is not described"
+  }.freeze
+
+  attr_reader :code
+
+  def initialize(code, info_message, method_id)
+    @code = code
+    @info_message = info_message
+    @method_id = method_id
+  end
+
+  def id
+    "#{@method_id}#{@code}#{@info_message}"
+  end
+
+  def warning_message
+    "WARNING (#{@code}): [#{@method_id}] -- #{@info_message}\n"
+  end
+
+  def warn
+    Warning.warn(warning_message)
+  end
+
+  def warn_through_writer
+    Apipie::Generator::Swagger::WarningWriter.instance.warn(self)
+  end
+
+  # @param [Integer] code
+  # @param [Hash] message_attributes
+  #
+  # @return [Apipie::Generator::Swagger::Warning]
+  def self.for_code(code, method_id, message_attributes = {})
+    if !CODES.value?(code)
+      raise ArgumentError, 'Unknown warning code'
+    end
+
+    info_message = if message_attributes.present?
+                     self::MESSAGES[code] % message_attributes
+                   else
+                     self::MESSAGES[code]
+                   end
+
+    Apipie::Generator::Swagger::Warning.new(code, info_message, method_id)
+  end
+end

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

@@ -0,0 +1,54 @@
+class Apipie::Generator::Swagger::WarningWriter
+  include Singleton
+
+  def initialize
+    @issued_warnings = []
+  end
+
+  # @param [Apipie::Generator::Swagger::Warning] warning
+  def warn(warning)
+    return if muted_warning?(warning)
+
+    warning.warn
+
+    @issued_warnings << warning.id
+  end
+
+  def issued_warnings?
+    @issued_warnings.count > 0
+  end
+
+  def clear!
+    @issued_warnings = []
+
+    self
+  end
+
+  private
+
+  # @param [Apipie::Generator::Swagger::Warning] warning
+  #
+  # @return [TrueClass, FalseClass]
+  def muted_warning?(warning)
+    @issued_warnings.include?(warning.id) ||
+      suppressed_warning?(warning.code) ||
+      suppress_warnings?
+  end
+
+  # @param [Integer] warning_number
+  #
+  # @return [TrueClass, FalseClass]
+  def suppressed_warning?(warning_number)
+    suppress_warnings_config.is_a?(Array) && suppress_warnings_config.include?(warning_number)
+  end
+
+  # @return [TrueClass, FalseClass]
+  def suppress_warnings?
+    suppress_warnings_config == true
+  end
+
+  # @return [FalseClass, TrueClass, Array]
+  def suppress_warnings_config
+    Apipie.configuration.generator.swagger.suppress_warnings
+  end
+end

data/lib/apipie/helpers.rb

@@ -0,0 +1,73 @@
+module Apipie
+  module Helpers
+    def markup_to_html(text)
+      return "" if text.nil?
+      if Apipie.configuration.markup.respond_to? :to_html
+        Apipie.configuration.markup.to_html(text.strip_heredoc)
+      else
+        text.strip_heredoc
+      end
+    end
+
+    attr_accessor :url_prefix
+
+    def request_script_name
+      Thread.current[:apipie_req_script_name] || ""
+    end
+
+    def request_script_name=(script_name)
+      Thread.current[:apipie_req_script_name] = script_name
+    end
+
+    def full_url(path)
+      unless @url_prefix
+        @url_prefix = ""
+        @url_prefix << request_script_name
+        @url_prefix << Apipie.configuration.doc_base_url
+      end
+      path = path.sub(%r{^/},"")
+      ret = "#{@url_prefix}/#{path}"
+      ret.insert(0,"/") unless %r{\A[./]}.match?(ret)
+      ret.sub!(%r{/*\Z},"")
+      ret
+    end
+
+    def include_javascripts
+      %w[ bundled/jquery.js
+          bundled/bootstrap-collapse.js
+          bundled/prettify.js
+          apipie.js ].map do |file|
+        "<script type='text/javascript' src='#{Apipie.full_url("javascripts/#{file}")}'></script>"
+      end.join("\n").html_safe
+    end
+
+    def include_stylesheets
+      %w[ bundled/bootstrap.min.css
+          bundled/prettify.css
+          bundled/bootstrap-responsive.min.css ].map do |file|
+        "<link type='text/css' rel='stylesheet' href='#{Apipie.full_url("stylesheets/#{file}")}'/>"
+      end.join("\n").html_safe
+    end
+
+    def label_class_for_error(err)
+      case err[:code]
+        when 200
+          'label label-info'
+        when 201
+          'label label-success'
+        when 204
+          'label label-info2'
+        when 401
+          'label label-warning'
+        when 403
+          'label label-warning2'
+        when 422
+          'label label-important'
+        when 404
+          'label label-inverse'
+        else
+          'label'
+      end
+    end
+  end
+end

data/lib/apipie/markup.rb

@@ -0,0 +1,52 @@
+module Apipie
+
+  module Markup
+
+    class RDoc
+
+      def initialize
+        require 'rdoc'
+        require 'rdoc/markup/to_html'
+      end
+
+      def to_html(text)
+        rdoc.convert(text)
+      end
+
+      private
+
+      def 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
+    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/method_description/api.rb

@@ -0,0 +1,12 @@
+class Apipie::MethodDescription::Api
+  attr_accessor :short_description, :path, :http_method, :from_routes,
+    :options, :returns
+
+  def initialize(method, path, desc, options)
+    @http_method = method.to_s
+    @path = path
+    @short_description = desc
+    @from_routes = options[:from_routes]
+    @options = options
+  end
+end

data/lib/apipie/method_description/apis_service.rb

@@ -0,0 +1,82 @@
+# Service that builds the appropriate Apipie::MethodDescription::Api
+# required by Apipie::MethodDescription
+#
+class Apipie::MethodDescription::ApisService
+  # @param [Apipie::ResourceDescription] resource
+  # @param [Symbol] controller_action
+  # @param [Hash] dsl
+  def initialize(resource, controller_action, dsl)
+    @resource = resource
+    @controller_action = controller_action
+    @dsl = dsl
+  end
+
+  # @return [Array<Apipie::MethodDescription::Api>]
+  def call
+    api_args.map do |http_method, path, desc, opts|
+      Apipie::MethodDescription::Api.new(
+        http_method,
+        concern_subst(path),
+        concern_subst(desc),
+        opts
+      )
+    end
+  end
+
+  private
+
+  def concern_subst(path)
+    return if path.blank?
+
+    if from_concern?
+      @resource.controller._apipie_perform_concern_subst(path)
+    else
+      path
+    end
+  end
+
+  # @return [Array<Array>]
+  def api_args
+    return @dsl[:api_args] if !api_from_routes?
+
+    api_args = @dsl[:api_args].dup
+
+    api_args_from_routes = routes.map do |route_info|
+      [
+        route_info[:verb],
+        route_info[:path],
+        route_info[:desc],
+        (route_info[:options] || {}).merge(from_routes: true)
+      ]
+    end
+
+    api_args.concat(api_args_from_routes)
+  end
+
+  def api_from_routes?
+    @dsl[:api_from_routes].present?
+  end
+
+  def from_concern?
+    @dsl[:from_concern] == true
+  end
+
+  def description
+    @dsl[:api_from_routes][:desc]
+  end
+
+  def options
+    @dsl[:api_from_routes][:options]
+  end
+
+  # @return [Array<Hash>]
+  def routes
+    Apipie.routes_for_action(
+      @resource.controller,
+      @controller_action,
+      { desc: description, options: options }
+    )
+  end
+end
+
+

data/lib/apipie/method_description.rb

@@ -0,0 +1,230 @@
+module Apipie
+  class MethodDescription
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :headers, :show
+    attr_accessor :metadata
+
+    def initialize(method, resource, dsl_data)
+      @method = method.to_s
+      @resource = resource
+      @from_concern = dsl_data[:from_concern]
+      @apis = ApisService.new(resource, method, dsl_data).call
+
+      @full_description = dsl_data[:description] || ''
+
+      @errors = dsl_data[:errors].map do |args|
+        Apipie::ErrorDescription.from_dsl_data(args)
+      end
+
+      @tag_list = dsl_data[:tag_list]
+
+      @returns = dsl_data[:returns].map do |code,args|
+        Apipie::ResponseDescription.from_dsl_data(self, code, args)
+      end
+
+      @see = dsl_data[:see].map do |args|
+        Apipie::SeeDescription.new(args)
+      end
+
+      @formats = dsl_data[:formats]
+      @examples = dsl_data[:examples]
+      @examples += load_recorded_examples
+
+      @metadata = dsl_data[:meta]
+
+      @params_ordered = dsl_data[:params].map do |args|
+        Apipie::ParamDescription.from_dsl_data(self, args)
+      end.reject(&:response_only?)
+
+      @params_ordered = ParamDescription.unify(@params_ordered)
+      @headers = dsl_data[:headers]
+
+      @show = if dsl_data.key? :show
+        dsl_data[:show]
+      else
+        true
+      end
+    end
+
+    def id
+      "#{resource._id}##{method}"
+    end
+
+    def params
+      params_ordered.reduce(ActiveSupport::OrderedHash.new) { |h,p| h[p.name] = p; h }
+    end
+
+    def params_ordered_self
+      @params_ordered
+    end
+
+    def params_ordered
+      all_params = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get params from parent resource description
+      [parent, @resource].compact.each do |resource|
+        resource_params = resource._params_args.map do |args|
+          Apipie::ParamDescription.from_dsl_data(self, args)
+        end
+        merge_params(all_params, resource_params)
+      end
+
+      merge_params(all_params, @params_ordered)
+      all_params.find_all(&:validator)
+    end
+
+    def returns_self
+      @returns
+    end
+
+    def tag_list
+      all_tag_list = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get tags from parent resource description
+      parent_tags = [parent, @resource].compact.flat_map(&:_tag_list_arg)
+      Apipie::TagListDescription.new((parent_tags + @tag_list).uniq.compact)
+    end
+
+    def returns
+      all_returns = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get response descriptions from parent resource description
+      [parent, @resource].compact.each do |resource|
+        resource_returns = resource._returns_args.map do |code, args|
+          Apipie::ResponseDescription.from_dsl_data(self, code, args)
+        end
+        merge_returns(all_returns, resource_returns)
+      end
+
+      merge_returns(all_returns, @returns)
+    end
+
+    def errors
+      return @merged_errors if @merged_errors
+      @merged_errors = []
+      if @resource
+        resource_errors = @resource._errors_args.map do |args|
+          Apipie::ErrorDescription.from_dsl_data(args)
+        end
+
+        # exclude overwritten parent errors
+        @merged_errors = resource_errors.find_all do |err|
+          !@errors.any? { |e| e.code == err.code }
+        end
+      end
+      @merged_errors.concat(@errors)
+      return @merged_errors
+    end
+
+    def version
+      resource._version
+    end
+
+    def doc_url
+      crumbs = []
+      crumbs << @resource._version if Apipie.configuration.version_in_url
+      crumbs << @resource._id
+      crumbs << @method
+      Apipie.full_url crumbs.join('/')
+    end
+
+    def create_api_url(api)
+      path = api.path
+      unless api.from_routes
+        path = "#{@resource._api_base_url}#{path}"
+      end
+      path = path[0..-2] if path[-1..-1] == '/'
+      return path
+    end
+
+    def method_apis_to_json(lang = nil)
+      @apis.each.collect do |api|
+        {
+          :api_url => create_api_url(api),
+          :http_method => api.http_method.to_s,
+          :short_description => Apipie.app.translate(api.short_description, lang),
+          :deprecated => resource._deprecated || api.options[:deprecated]
+        }
+      end
+    end
+
+    def see
+      @see
+    end
+
+    def formats
+      @formats || @resource._formats
+    end
+
+    def to_json(lang = nil)
+      {
+        :doc_url => doc_url,
+        :name => @method,
+        :apis => method_apis_to_json(lang),
+        :formats => formats,
+        :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,
+        :metadata => @metadata,
+        :see => see.map(&:to_json),
+        :headers => headers,
+        :show => @show
+      }
+    end
+
+    # was the description defines in a module instead of directly in controller?
+    def from_concern?
+      @from_concern
+    end
+
+    def method_name
+      @method
+    end
+
+    private
+
+    def merge_params(params, new_params)
+      new_param_names = Set.new(new_params.map(&:name))
+      params.delete_if { |p| new_param_names.include?(p.name) }
+      params.concat(new_params)
+    end
+
+    def merge_returns(returns, new_returns)
+      new_return_codes = Set.new(new_returns.map(&:code))
+      returns.delete_if { |p| new_return_codes.include?(p.code) }
+      returns.concat(new_returns)
+    end
+
+    def load_recorded_examples
+      (Apipie.recorded_examples[id] || []).
+        find_all { |ex| ex["show_in_doc"].to_i > 0 }.
+        find_all { |ex| ex["versions"].nil? || ex["versions"].include?(self.version) }.
+        sort_by { |ex| ex["show_in_doc"] }.
+        map { |ex| format_example(ex.symbolize_keys) }
+    end
+
+    def format_example_data(data)
+      case data
+      when Array, Hash
+        JSON.pretty_generate(data).gsub(/: \[\s*\]/,": []").gsub(/\{\s*\}/,"{}")
+      else
+        data
+      end
+    end
+
+    def format_example(ex)
+      example = ""
+      example << "// #{ex[:title]}\n" if ex[:title].present?
+      example << "#{ex[:verb]} #{ex[:path]}"
+      example << "?#{ex[:query]}" unless ex[:query].blank?
+      example << "\n" << format_example_data(ex[:request_data]).to_s if ex[:request_data]
+      example << "\n" << ex[:code].to_s
+      example << "\n" << format_example_data(ex[:response_data]).to_s if ex[:response_data]
+      example
+    end
+  end
+end

data/lib/apipie/middleware/checksum_in_headers.rb

@@ -0,0 +1,35 @@
+# Middleware for rails app that adds checksum of JSON in the response headers
+# which can help client to realize when JSON has changed
+#
+# Add the following to your application.rb
+#   require 'apipie/middleware/checksum_in_headers'
+#   # Add JSON checksum in headers for smarter caching
+#   config.middleware.use "Apipie::Middleware::ChecksumInHeaders"
+#
+# And in your apipie initializer allow checksum calculation
+#   Apipie.configuration.update_checksum = true
+# and reload documentation
+#   Apipie.reload_documentation
+#
+# By default the header is added to requests on /api and /apipie only
+# It can be changed with
+#   Apipie.configuration.checksum_path = ['/prefix/api']
+# If set to nil the header is added always
+
+module Apipie
+  module Middleware
+    class ChecksumInHeaders
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        if !Apipie.configuration.checksum_path || env['PATH_INFO'].start_with?(*Apipie.configuration.checksum_path)
+          headers.merge!( 'Apipie-Checksum' => Apipie.checksum )
+        end
+        return [status, headers, body]
+      end
+    end
+  end
+end

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