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

data/lib/apipie/response_description_adapter.rb

@@ -0,0 +1,202 @@
+module Apipie
+
+  def self.prop(name, expected_type, options = {}, sub_properties = [])
+    Apipie::ResponseDescriptionAdapter::PropDesc.new(name, expected_type, options, sub_properties)
+  end
+
+  def self.additional_properties(yesno)
+    Apipie::ResponseDescriptionAdapter::AdditionalPropertiesModifier.new(yesno)
+  end
+
+  class ResponseDescriptionAdapter
+    class Modifier
+      def apply(adapter)
+        raise "Modifier subclass must implement 'apply' method"
+      end
+    end
+
+    class AdditionalPropertiesModifier < Modifier
+      def initialize(additional_properties_allowed)
+        @additional_properties_allowed = additional_properties_allowed
+      end
+
+      def apply(adapter)
+        adapter.additional_properties =  @additional_properties_allowed
+      end
+    end
+  end
+
+
+  class ResponseDescriptionAdapter
+
+    #
+    # A ResponseDescriptionAdapter::PropDesc object pretends to be an Apipie::Param in a ResponseDescription
+    #
+    # To successfully masquerade as such, it needs to:
+    #    respond_to?('name') and/or ['name'] returning the name of the parameter
+    #    respond_to?('required') and/or ['required'] returning boolean
+    #    respond_to?('additional_properties') and/or ['additional_properties'] returning boolean
+    #    respond_to?('validator') and/or ['validator'] returning 'nil' (so type is 'string'), or an object that:
+    #           1) describes a type.  currently type is inferred as follows:
+    #                 if validator.is_a? Apipie::Validator::EnumValidator -->  respond_to? 'values' (returns array).  Type is enum or boolean
+    #                 else: use v.expected_type().  This is expected to be the swagger type, or:
+    #                     numeric ==> swagger type is 'number'
+    #                     hash ==> swagger type is 'object' and validator should respond_to? 'params_ordered'
+    #                     array ==> swagger type is array and validator (FUTURE) should indicate type of element
+
+    class PropDesc
+
+      def to_s
+        "PropDesc -- name: #{@name}  type: #{@expected_type} required: #{@required} options: #{@options} subprop count: #{@sub_properties.length} additional properties: #{@additional_properties}"
+      end
+
+      #
+      # a ResponseDescriptionAdapter::PropDesc::Validator pretends to be an Apipie::Validator
+      #
+      class Validator
+        attr_reader :expected_type
+
+        def [](key)
+          self.send(key) if self.respond_to?(key.to_s)
+        end
+
+        def initialize(expected_type, enum_values = nil, sub_properties = nil)
+          @expected_type = expected_type
+          @enum_values = enum_values
+          @is_enum = !!enum_values
+          @sub_properties = sub_properties
+        end
+
+        def is_enum?
+          !!@is_enum
+        end
+
+        def values
+          @enum_values
+        end
+
+        def params_ordered
+          raise "Only validators with expected_type 'object' can have sub-properties" unless @expected_type == 'object'
+          @sub_properties
+        end
+      end
+
+      #======================================================================
+
+
+      def initialize(name, expected_type, options = {}, sub_properties = [])
+        @name = name
+        @required = true
+        @required = false if options[:required] == false
+        @expected_type = expected_type
+        @additional_properties = false
+
+        options[:desc] ||= options[:description]
+        @description = options[:desc]
+        @options = options
+        @is_array = options[:is_array] || false
+        @sub_properties = []
+        for prop in sub_properties do
+          add_sub_property(prop)
+        end
+      end
+
+      def [](key)
+        self.send(key) if self.respond_to?(key.to_s)
+      end
+
+      def add_sub_property(prop_desc)
+        raise "Only properties with expected_type 'object' can have sub-properties" unless @expected_type == 'object'
+        case prop_desc
+        when PropDesc
+          @sub_properties << prop_desc
+        when Modifier
+          prop_desc.apply(self)
+        else
+          raise "Unrecognized prop_desc type (#{prop_desc.class})"
+        end
+      end
+
+      def to_json(lang)
+        {
+            name: name,
+            required: required,
+            validator: validator,
+            description: description,
+            additional_properties: additional_properties,
+            is_array: is_array?,
+            options: options
+        }
+      end
+      attr_reader :name, :required, :expected_type, :options, :description
+      attr_accessor :additional_properties
+
+      alias desc description
+
+      def is_array?
+        @is_array
+      end
+
+      def validator
+        Validator.new(@expected_type, options[:values], @sub_properties)
+      end
+    end
+  end
+
+  #======================================================================
+
+  class ResponseDescriptionAdapter
+
+    def self.from_self_describing_class(cls)
+      adapter = ResponseDescriptionAdapter.new(cls.to_s)
+      props = cls.describe_own_properties
+      adapter.add_property_descriptions(props)
+      adapter
+    end
+
+    def initialize(typename)
+      @property_descs = []
+      @additional_properties = false
+      @typename = typename
+    end
+
+    attr_accessor :additional_properties, :typename
+
+    def allow_additional_properties
+      additional_properties
+    end
+
+    def to_json
+      params_ordered.to_json
+    end
+
+    def add(prop_desc)
+      case prop_desc
+      when PropDesc
+        @property_descs << prop_desc
+      when Modifier
+        prop_desc.apply(self)
+      else
+        raise "Unrecognized prop_desc type (#{prop_desc.class})"
+      end
+    end
+
+    def add_property_descriptions(prop_descs)
+      for prop_desc in prop_descs
+        add(prop_desc)
+      end
+    end
+
+    def property(name, expected_type, options)
+      @property_descs << PropDesc.new(name, expected_type, options)
+    end
+
+    def params_ordered
+      @property_descs
+    end
+
+    def is_array?
+      false
+    end
+  end
+end

data/lib/apipie/routes_formatter.rb

@@ -0,0 +1,33 @@
+module Apipie
+  class RoutesFormatter
+    API_METHODS = %w{GET POST PUT PATCH OPTIONS DELETE}.freeze
+
+    # The entry method called by Apipie to extract the array
+    # representing the api dsl from the routes definition.
+    def format_routes(rails_routes, args)
+      rails_routes.map { |rails_route| format_route(rails_route, args) }
+    end
+
+    def format_route(rails_route, args)
+      { :path => format_path(rails_route),
+        :verb => format_verb(rails_route),
+        :desc => args[:desc],
+        :options => args[:options] }
+    end
+
+    def format_path(rails_route)
+      File.join(rails_route.base_url, rails_route.path.spec.to_s.gsub('(.:format)', ''))
+    end
+
+    def format_verb(rails_route)
+      verb = API_METHODS.select{|defined_verb| defined_verb =~ /\A#{rails_route.verb}\z/}
+      if verb.count != 1
+        verb = API_METHODS.select{|defined_verb| defined_verb == rails_route.constraints[:method]}
+        if verb.blank?
+          raise "Unknown verb #{rails_route.path.spec.to_s}"
+        end
+      end
+      verb.first
+    end
+  end
+end

data/lib/apipie/routing.rb

@@ -0,0 +1,16 @@
+module Apipie
+  module Routing
+    module MapperExtensions
+      def apipie(options = {})
+        namespace "apipie", :path => Apipie.configuration.doc_base_url do
+          get 'apipie_checksum', :to => "apipies#apipie_checksum", :format => "json"
+          constraints(:version => %r{[^/]+}, :resource => %r{[^/]+}, :method => %r{[^/]+}) do
+            get(options.reverse_merge("(:version)/(:resource)/(:method)" => "apipies#index", :as => :apipie))
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.send :include, Apipie::Routing::MapperExtensions

data/lib/apipie/rspec/response_validation_helper.rb

@@ -0,0 +1,194 @@
+#----------------------------------------------------------------------------------------------
+# response_validation_helper.rb:
+#
+# this is an rspec utility to allow validation of responses against the swagger schema generated
+# from the Apipie 'returns' definition for the call.
+#
+#
+# to use this file in a controller rspec you should
+# require 'apipie/rspec/response_validation_helper' in the spec file
+#
+#
+# this utility provides two mechanisms:  matcher-based validation and auto-validation
+#
+#   matcher-based: an rspec matcher allowing 'expect(response).to match_declared_responses'
+#   auto-validation: all responses returned from 'get', 'post', etc. are automatically tested
+#
+# ===================================
+# Matcher-based validation - example
+# ===================================
+# Assume the file 'my_controller_spec.rb':
+#
+#     require 'apipie/rspec/response_validation_helper'
+#
+#     RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+#
+#     describe "GET stuff with response validation" do
+#       render_views   # this makes sure the 'get' operation will actually
+#                      # return the rendered view even though this is a Controller spec
+#
+#       it "does something" do
+#         response = get :index, {format: :json}
+#
+#         # the following expectation will fail if the returned object
+#         # does not match the 'returns' declaration in the Controller,
+#         # or if there is no 'returns' declaration for the returned
+#         # HTTP status code
+#         expect(response).to match_declared_responses
+#       end
+#     end
+#
+#
+# ===================================
+# Auto-validation
+# ===================================
+# To use auto-validation, at the beginning of the block in which you want to turn on validation:
+#    -) turn on view rendering (by stating 'render_views')
+#    -) turn on response validation by stating 'auto_validate_rendered_views'
+#
+# For example, assume the file 'my_controller_spec.rb':
+#
+#     require 'apipie/rspec/response_validation_helper'
+#
+#     RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+#
+#     describe "GET stuff with response validation" do
+#       render_views
+#       auto_validate_rendered_views
+#
+#       it "does something" do
+#         get :index, {format: :json}
+#       end
+#       it "does something else" do
+#         get :another_index, {format: :json}
+#       end
+#     end
+#
+#     describe "GET stuff without response validation" do
+#       it "does something" do
+#         get :index, {format: :json}
+#       end
+#       it "does something else" do
+#         get :another_index, {format: :json}
+#       end
+#     end
+#
+#
+# Once this is done, responses from http operations ('get', 'post', 'delete', etc.)
+# will fail the test if the response structure does not match the 'returns' declaration
+# on the method (for the actual HTTP status code), or if there is no 'returns' declaration
+# for the HTTP status code.
+#----------------------------------------------------------------------------------------------
+
+
+#----------------------------------------------------------------------------------------------
+# Response validation: core logic  (used by auto-validation and manual-validation mechanisms)
+#----------------------------------------------------------------------------------------------
+class ActionController::Base
+  module Apipie::ControllerValidationHelpers
+    # this method is injected into ActionController::Base in order to
+    # get access to the names of the current controller, current action, as well as to the response
+    def schema_validation_errors_for_response
+      unprocessed_schema = Apipie::json_schema_for_method_response(controller_name, action_name, response.code, true)
+
+      if unprocessed_schema.nil?
+        err = "no schema defined for #{controller_name}##{action_name}[#{response.code}]"
+        return [nil, [err], RuntimeError.new(err)]
+      end
+
+      schema = JSON.parse(JSON(unprocessed_schema))
+
+      error_list = JSON::Validator.fully_validate(schema, response.body, :strict => false, :version => :draft4, :json => true)
+
+      error_object = Apipie::ResponseDoesNotMatchSwaggerSchema.new(controller_name, action_name, response.code, error_list, schema, response.body)
+
+      [schema, error_list, error_object]
+    rescue Apipie::NoDocumentedMethod
+      [nil, [], nil]
+    end
+  end
+
+  include Apipie::ControllerValidationHelpers
+end
+
+module Apipie
+  def self.print_validation_errors(validation_errors, schema, response, error_object = nil)
+    Rails.logger.warn(validation_errors.to_s)
+    if Rails.env.test?
+      puts "schema validation errors:"
+      validation_errors.each { |e| puts "--> #{e.to_s}" }
+      puts "schema:  #{schema.nil? ? '<none>' : JSON(schema)}"
+      puts "response: #{response.body}"
+      raise error_object if error_object
+    end
+  end
+end
+
+#---------------------------------
+# Manual-validation (RSpec matcher)
+#---------------------------------
+RSpec::Matchers.define :match_declared_responses do
+  match do |actual|
+    (schema, validation_errors) = subject.send(:schema_validation_errors_for_response)
+    valid = (validation_errors == [])
+    Apipie::print_validation_errors(validation_errors, schema, response) unless valid
+
+    valid
+  end
+end
+
+
+#---------------------------------
+# Auto-validation logic
+#---------------------------------
+module RSpec::Rails::ViewRendering
+  # Augment the RSpec DSL
+  module ClassMethods
+    def auto_validate_rendered_views
+      before do
+        @is_response_validation_on = true
+      end
+
+      after do
+        @is_response_validation_on = false
+      end
+    end
+  end
+end
+
+
+ActionController::TestCase::Behavior.instance_eval do
+  # instrument the 'process' method in ActionController::TestCase to enable response validation
+  module Apipie::ResponseValidationHelpers
+    @is_response_validation_on = false
+    def process(*, **)
+      result = super
+      validate_response if @is_response_validation_on
+
+      result
+    end
+
+    def validate_response
+      controller.send(:validate_response_and_abort_with_info_if_errors)
+    end
+  end
+
+  prepend Apipie::ResponseValidationHelpers
+end
+
+
+class ActionController::Base
+  module Apipie::ControllerValidationHelpers
+    def validate_response_and_abort_with_info_if_errors
+
+      (schema, validation_errors, error_object) = schema_validation_errors_for_response
+
+      valid = (validation_errors == [])
+      if !valid
+        Apipie::print_validation_errors(validation_errors, schema, response, error_object)
+      end
+    end
+  end
+end
+
+

data/lib/apipie/see_description.rb

@@ -0,0 +1,39 @@
+module Apipie
+
+  class SeeDescription
+
+    attr_reader :link, :description
+
+    def initialize(args)
+      if args.first.is_a? Hash
+        args = args.first
+      elsif args.count == 2
+        if args.last.is_a? Hash
+          args = {:link => args.first}.merge(args.last)
+        else
+          args = {:link => args.first, :description => args.second}
+        end
+      elsif args.count == 1 && args.first.is_a?(String)
+        args = {:link => args.first, :description => args.first}
+      else
+        raise ArgumentError "ApipieError: Bad use of see method."
+      end
+      @link = args[:link] || args['link']
+      @description = args[:desc] || args[:description] || args['desc'] || args['description']
+    end
+
+    def to_json
+      {:link => see_url, :description => description}
+    end
+
+    def see_url
+      method_description = Apipie[@link]
+      if method_description.nil?
+        raise ArgumentError.new("Method #{@link} referenced in 'see' does not exist.")
+      end
+      method_description.doc_url
+    end
+
+  end
+
+end

data/lib/apipie/static_dispatcher.rb

@@ -0,0 +1,75 @@
+module Apipie
+
+  class FileHandler
+    def initialize(root)
+      @root          = root.chomp('/')
+      @compiled_root = /^#{Regexp.escape(root)}/
+      @file_server   = if defined?(::Rack::Files)
+                         ::Rack::Files.new(@root)
+                       else
+                         # Deprecated in Rack 3.0, kept
+                         # for backward compatibility
+                         ::Rack::File.new(@root)
+                       end
+    end
+
+    def match?(path)
+      # Replace all null bytes
+      path = ::Rack::Utils.unescape(path || '')
+        .encode(Encoding::UTF_8, invalid: :replace, replace: '')
+        .gsub("\x0", '')
+
+      full_path = path.empty? ? @root : File.join(@root, path)
+      paths = "#{full_path}#{ext}"
+
+      matches = Dir[paths]
+      match = matches.detect { |m| File.file?(m) }
+      if match
+        match.sub!(@compiled_root, '')
+        match
+      end
+    end
+
+    delegate :call, to: :@file_server
+
+    def ext
+      @ext ||= begin
+        ext = cache_extension
+        "{,#{ext},/index#{ext}}"
+      end
+    end
+
+    def cache_extension
+      if ::ActionController::Base.respond_to?(:default_static_extension)
+        ::ActionController::Base.default_static_extension
+      else
+        ::ActionController::Base.page_cache_extension
+      end
+
+    end
+  end
+
+  class StaticDispatcher
+    # Dispatches the static files. Similar to ActionDispatch::Static, but
+    # it supports different baseurl configurations
+    def initialize(app, path)
+      @app = app
+      @file_handler = Apipie::FileHandler.new(path)
+    end
+
+    def call(env)
+      @baseurl ||= Apipie.configuration.doc_base_url
+      case env['REQUEST_METHOD']
+      when 'GET', 'HEAD'
+        path = env['PATH_INFO'].sub("#{@baseurl}/","/apipie/").chomp('/')
+
+        if match = @file_handler.match?(path)
+          env["PATH_INFO"] = match
+          return @file_handler.call(env)
+        end
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/apipie/swagger_generator.rb

@@ -0,0 +1,45 @@
+module Apipie
+  class SwaggerGenerator
+    # @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 self.json_schema_for_method_response(method, return_code, allow_nulls)
+      response = method.returns.find { |response| response.code.to_s == return_code.to_s }
+
+      return if response.blank?
+
+      http_method = method.apis.first.http_method
+
+      schema = Apipie::Generator::Swagger::MethodDescription::ResponseSchemaService.new(
+        response,
+        allow_null: allow_nulls,
+        http_method: http_method,
+        controller_method: method
+      ).to_swagger
+
+      definitions = Apipie::Generator::Swagger::ReferencedDefinitions.instance.definitions
+
+      if definitions.present?
+        schema[:definitions] = definitions
+      end
+
+      schema
+    end
+
+    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
+    end
+  end
+end

data/lib/apipie/tag_list_description.rb

@@ -0,0 +1,11 @@
+module Apipie
+
+  class TagListDescription
+
+    attr_reader :tags
+
+    def initialize(tags); @tags = tags; end
+
+  end
+
+end