apipie-rails 0.8.1 → 0.9.0

data/CHANGELOG.md

@@ -4,6 +4,30 @@
 Also deleted the `Gemfile` that was now a broken symlink.
 please use `export BUNDLE_GEMFILE='gemfiles/Gemfile.rails61'; bundle exec rspec` to run the test suite
 
+
+
+## [v0.9.0](https://github.com/Apipie/apipie-rails/tree/v0.9.0) (2023-01-03)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.8.2...v0.9.0)
+* [Refactor] Move Swagger types and warnings under `/generator` namespace [#803](https://github.com/Apipie/apipie-rails/pull/803) (Panos Dalitsouris)
+* [Refactor] Creates `Apipie::MethodDescription::ApisService` [#805](https://github.com/Apipie/apipie-rails/pull/805) (Panos Dalitsouris)
+* [Refactor] Change output folder to `spec/dummy/tmp/` [#804](https://github.com/Apipie/apipie-rails/pull/804) (Panos Dalitsouris)
+* Fix tiny typo in docs [#798](https://github.com/Apipie/apipie-rails/pull/798) (Erik-B. Ernst)
+* Fix Generated docs.json output [#787](https://github.com/Apipie/apipie-rails/pull/787) (Jeremy Liberman)
+* Rubocop Fixes [#775](https://github.com/Apipie/apipie-rails/pull/775), [#778](https://github.com/Apipie/apipie-rails/pull/778), [#780](https://github.com/Apipie/apipie-rails/pull/780), [#790](https://github.com/Apipie/apipie-rails/pull/790), [#783](https://github.com/Apipie/apipie-rails/pull/783), [#785](https://github.com/Apipie/apipie-rails/pull/785) (RuboCop)
+* Remove/clean up dev dependencies and unused rake tasks [#777](https://github.com/Apipie/apipie-rails/pull/777) (Mathieu Jobin)
+    - remove unused rake task
+* Setup Rubocop Challenger [#776](https://github.com/Apipie/apipie-rails/pull/776) (Mathieu Jobin)
+
+## [v0.8.2](https://github.com/Apipie/apipie-rails/tree/v0.8.2) (2022-09-03)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.8.1...v0.8.2)
+* Allow custom validators to opt out of allow_blank behavior [#762](https://github.com/Apipie/apipie-rails/pull/762).  (Stephen Hanson)
+* Enforce test coverage, set current 89% as minimum [#764](https://github.com/Apipie/apipie-rails/pull/764). (Mathieu Jobin)
+* Add contributing instructions to readme [#763](https://github.com/Apipie/apipie-rails/pull/763).  (Stephen Hanson)
+* Fix readme formatting [#765](https://github.com/Apipie/apipie-rails/pull/765).  (Stephen Hanson)
+* Adds expected_type to IntegerValidator example [#769](https://github.com/Apipie/apipie-rails/pull/769).  (Jeremy Liberman)
+* Update readme with error handling example [#768](https://github.com/Apipie/apipie-rails/pull/768).  (Jesse Eisenberg)
+* Fix scope incorrectly set to nil when a param_group is used inside an array_of_hash and the param_group is in a different module / controller. [#693](https://github.com/Apipie/apipie-rails/pull/693) [#774](https://github.com/Apipie/apipie-rails/pull/774).  (Omkar Joshi / Oliver Iyer)
+
 ## [v0.8.1](https://github.com/Apipie/apipie-rails/tree/v0.8.1) (2022-05-26)
 [Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.8.0...v0.8.1)
 * Remove warning that came back as of [#752](https://github.com/Apipie/apipie-rails/pull/752). [#761](https://github.com/Apipie/apipie-rails/pull/761) (Jorge Santos / Mathieu Jobin)

data/README.rst

@@ -2,8 +2,8 @@
  API Documentation Tool
 ========================
 
-.. image:: https://travis-ci.org/Apipie/apipie-rails.svg?branch=master
-    :target: https://travis-ci.org/Apipie/apipie-rails
+.. image:: https://github.com/Apipie/apipie-rails/actions/workflows/build.yml/badge.svg
+    :target: https://github.com/Apipie/apipie-rails/actions/workflows/build.yml
 .. image:: https://codeclimate.com/github/Apipie/apipie-rails.svg
     :target: https://codeclimate.com/github/Apipie/apipie-rails
 .. image:: https://badges.gitter.im/Apipie/apipie-rails.svg
@@ -1156,6 +1156,21 @@ is raised and can be rescued and processed. It contains a description
 of the parameter value expectations. Validations can be turned off
 in the configuration file.
 
+Here is an example of how to rescue and process a +ParamMissing+ or
++ParamInvalid+ error from within the ApplicationController.
+
+.. code:: ruby
+  
+  class ApplicationController < ActionController::Base
+
+    # ParamError is superclass of ParamMissing, ParamInvalid
+    rescue_from Apipie::ParamError do |e|
+      render text: e.message, status: :unprocessable_entity
+    end
+
+    # ...
+  end
+
 Parameter validation normally happens after before_actions, just before
 your controller method is invoked. If you prefer to control when parameter
 validation occurs, set the configuration parameter ``validate`` to ``:explicitly``.
@@ -1368,6 +1383,10 @@ So we create apipie_validators.rb initializer with this content:
      def description
        "Must be #{@type}."
      end
+
+     def expected_type
+       'numeric'
+     end
    end
 
 Parameters of the build method:
@@ -1385,6 +1404,16 @@ options
 block
   Block converted into Proc, use it as you desire. In this example nil.
 
+If your validator includes valid values that respond true to `.blank?`, you
+should also define:
+
+.. code:: ruby
+
+   def ignore_allow_blank?
+     true
+   end
+
+so that the validation does not fail for valid values.
 
 ============
  Versioning
@@ -1872,6 +1901,20 @@ provided it uses Apipie as a backend.
 
 And if you write one on your own, don't hesitate to share it with us!
 
+====================
+ Contributing
+====================
+
+Since this gem does not have a Gemfile, you need to specify it in your shell with:
+
+.. code:: shell
+   BUNDLE_GEMFILE='gemfiles/Gemfile.rails61'
+
+Then, you can install dependencies and run the test suite:
+
+.. code:: shell
+   > bundle install
+   > bundle exec rspec
 
 ====================
  Disqus Integration

data/Rakefile

@@ -6,8 +6,3 @@ RSpec::Core::RakeTask.new(:spec)
 desc 'Default: run specs.'
 task :default => :spec
 
-desc "Generate code coverage"
-RSpec::Core::RakeTask.new(:coverage) do |t|
-  t.rcov = true
-  t.rcov_opts = ['--exclude', 'spec']
-end

data/apipie-rails.gemspec

@@ -1,5 +1,5 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
+$:.push File.expand_path('lib', __dir__)
 require "apipie/version"
 
 Gem::Specification.new do |s|
@@ -18,12 +18,16 @@ Gem::Specification.new do |s|
 
   s.add_dependency "actionpack", ">= 5.0"
   s.add_dependency "activesupport", ">= 5.0"
+
+  # Optional dependencies
+  s.add_development_dependency "maruku"   # for Markdown support
+  s.add_development_dependency "RedCloth" # for Textile support
+
+  # Dev/tests only dependencies
+  s.add_development_dependency "json-schema", "~> 2.8"
   s.add_development_dependency "rspec-rails", "~> 3.0"
-  s.add_development_dependency "sqlite3"
-  s.add_development_dependency "minitest"
-  s.add_development_dependency "maruku"
-  s.add_development_dependency "RedCloth"
   s.add_development_dependency "rake"
-  s.add_development_dependency "rdoc"
-  s.add_development_dependency "json-schema", "~> 2.8"
+  s.add_development_dependency 'rubocop_challenger'
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "sqlite3"
 end

data/lib/apipie/dsl_definition.rb

@@ -278,7 +278,7 @@ module Apipie
             end
           end
 
-          if (Apipie.configuration.validate == :implicitly || Apipie.configuration.validate == true)
+          if Apipie.configuration.validate == :implicitly || Apipie.configuration.validate == true
             old_method = instance_method(description.method)
 
             define_method(description.method) do |*args|
@@ -360,7 +360,7 @@ module Apipie
       # Reuses param group for this method. The definition is looked up
       # in scope of this controller. If the group was defined in
       # different controller, the second param can be used to specify it.
-      # when using action_aware parmas, you can specify :as =>
+      # when using action_aware params, you can specify :as =>
       # :create or :update to explicitly say how it should behave
       def param_group(name, scope_or_options = nil, options = {})
         if scope_or_options.is_a? Hash
@@ -533,7 +533,7 @@ module Apipie
       end
 
       def _apipie_perform_concern_subst(string)
-        return _apipie_concern_subst.reduce(string) do |ret, (key, val)|
+        _apipie_concern_subst.reduce(string) do |ret, (key, val)|
           ret.gsub(":#{key}", val)
         end
       end

data/lib/apipie/extractor/writer.rb

@@ -116,7 +116,7 @@ module Apipie
 
       def convert_file_value hash
         hash.each do |k, v|
-          if (v.is_a?(Rack::Test::UploadedFile) || v.is_a?(ActionDispatch::Http::UploadedFile))
+          if v.is_a?(Rack::Test::UploadedFile) || v.is_a?(ActionDispatch::Http::UploadedFile)
             hash[k] = "<FILE CONTENT '#{v.original_filename}'>"
           elsif v.is_a?(Hash)
             hash[k] = convert_file_value(v)
@@ -323,7 +323,7 @@ module Apipie
           desc ||= case @action.to_s
                    when "show", "create", "update", "destroy"
                      name = name.singularize
-                     "#{@action.capitalize} #{name =~ /^[aeiou]/ ? "an" : "a"} #{name}"
+                     "#{@action.capitalize} #{name =~ /^[aeiou]/ ? 'an' : 'a'} #{name}"
                    when "index"
                      "List #{name}"
                    end

data/lib/apipie/generator/generator.rb

@@ -0,0 +1,2 @@
+module Apipie::Generator
+end

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

@@ -0,0 +1,2 @@
+module Apipie::Generator::Swagger
+end

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

@@ -0,0 +1,16 @@
+class Apipie::Generator::Swagger::Type
+  attr_reader :str_format
+
+  def initialize(type, str_format = nil)
+    @type = type
+    @str_format = str_format
+  end
+
+  def to_s
+    @type
+  end
+
+  def ==(other)
+    other.to_s == self.to_s
+  end
+end

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

@@ -0,0 +1,70 @@
+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')
+  }
+
+  # @param [Apipie::Validator::BaseValidator, ResponseDescriptionAdapter::PropDesc::Validator, nil] validator
+  def initialize(validator)
+    @validator = validator
+  end
+
+  # @param [Hash<Symbol, Apipie::Generator::Swagger::Warning>] warnings
+  def extract_with_warnings(warnings = {})
+    if boolean? && warnings[:boolean].present?
+      Apipie::Generator::Swagger::WarningWriter.instance.warn(warnings[:boolean])
+    end
+
+    extract
+  end
+
+  private
+
+  def extract
+    expected_type =
+      if string?
+        :string
+      elsif boolean?
+        :boolean
+      elsif enum?
+        :enum
+      else
+        @validator.expected_type.to_sym
+      end
+
+    TYPES[expected_type] || @validator.expected_type
+  end
+
+  def string?
+    @validator.blank?
+  end
+
+  def enum?
+    @validator.is_a?(Apipie::Validator::EnumValidator) ||
+      (@validator.respond_to?(:is_enum?) && @validator.is_enum?)
+  end
+
+  def boolean?
+    @_boolean ||= enum? && boolean_values?
+  end
+
+  def boolean_values?
+    @validator.values.to_set == Set.new([true, false])
+  end
+end

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

@@ -0,0 +1,77 @@
+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
+  INFERRING_BOOLEAN_CODE = 108
+
+  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,
+    inferring_boolean: INFERRING_BOOLEAN_CODE
+  }
+
+  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",
+    INFERRING_BOOLEAN_CODE => "The parameter [%{parameter}] is Enum with [true, false] values. Inferring 'boolean'"
+  }
+
+  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}"
+  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.values.include?(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,48 @@
+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
+
+  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.swagger_suppress_warnings
+  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

@@ -1,22 +1,6 @@
-require 'set'
 module Apipie
 
   class MethodDescription
-
-    class 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
-
     attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :headers, :show
     attr_accessor :metadata
 
@@ -24,9 +8,7 @@ module Apipie
       @method = method.to_s
       @resource = resource
       @from_concern = dsl_data[:from_concern]
-      @apis = api_data(dsl_data).map do |mthd, path, desc, opts|
-        MethodDescription::Api.new(mthd, concern_subst(path), concern_subst(desc), opts)
-      end
+      @apis = ApisService.new(resource, method, dsl_data).call
 
       desc = dsl_data[:description] || ''
       @full_description = Apipie.markup_to_html(desc)
@@ -203,23 +185,6 @@ module Apipie
 
     private
 
-    def api_data(dsl_data)
-      ret = dsl_data[:api_args].dup
-      if dsl_data[:api_from_routes]
-        desc = dsl_data[:api_from_routes][:desc]
-        options = dsl_data[:api_from_routes][:options]
-
-        api_from_routes = Apipie.routes_for_action(resource.controller, method, {:desc => desc, :options => options}).map do |route_info|
-          [route_info[:verb],
-           route_info[:path],
-           route_info[:desc],
-           (route_info[:options] || {}).merge(:from_routes => true)]
-        end
-        ret.concat(api_from_routes)
-      end
-      ret
-    end
-
     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) }
@@ -259,16 +224,6 @@ module Apipie
       example << "\n" << format_example_data(ex[:response_data]).to_s if ex[:response_data]
       example
     end
-
-    def concern_subst(string)
-      return if string.nil?
-      if from_concern?
-        resource.controller._apipie_perform_concern_subst(string)
-      else
-        string
-      end
-    end
-
   end
 
 end

data/lib/apipie/param_description.rb

@@ -125,7 +125,7 @@ module Apipie
     end
 
     def blank_forbidden?
-      !Apipie.configuration.ignore_allow_blank_false && !allow_blank && !validator.is_a?(Validator::BooleanValidator)
+      !Apipie.configuration.ignore_allow_blank_false && !allow_blank && !validator.ignore_allow_blank?
     end
 
     def process_value(value)