apipie-rails 0.8.2 → 0.9.1

data/lib/apipie/swagger_generator.rb

@@ -128,33 +128,75 @@ module Apipie
       method.resource.controller.name + "#" + method.method
     end
 
+    def warn_missing_method_summary
+      warn(Apipie::Generator::Swagger::Warning::MISSING_METHOD_SUMMARY_CODE)
+    end
 
-    def warn_missing_method_summary() warn 100, "missing short description for method"; end
-    def warn_added_missing_slash(path) warn 101,"added missing / at beginning of path: #{path}"; end
-    def warn_no_return_codes_specified()  warn 102,"no return codes ('errors') specified"; end
-    def warn_hash_without_internal_typespec(param_name)  warn 103,"the parameter :#{param_name} is a generic Hash without an internal type specification"; end
-    def warn_optional_param_in_path(param_name) warn 104, "the parameter :#{param_name} is 'in-path'.  Ignoring 'not required' in DSL"; end
-    def warn_optional_without_default_value(param_name) warn 105,"the parameter :#{param_name} is optional but default value is not specified (use :default_value => ...)"; end
-    def warn_param_ignored_in_form_data(param_name) warn 106,"ignoring param :#{param_name} -- cannot include Hash without fields in a formData specification"; end
-    def warn_path_parameter_not_described(name,path) warn 107,"the parameter :#{name} appears in the path #{path} but is not described"; end
-    def warn_inferring_boolean(name) warn 108,"the parameter [#{name}] is Enum with [true,false] values. Inferring 'boolean'"; end
-
-    def warn(warning_num, msg)
-      suppress = Apipie.configuration.swagger_suppress_warnings
-      return if suppress == true
-      return if suppress.is_a?(Array) && suppress.include?(warning_num)
+    def warn_added_missing_slash(path)
+      warn(
+        Apipie::Generator::Swagger::Warning::ADDED_MISSING_SLASH_CODE,
+        { path: path }
+      )
+    end
 
-      method_id = ruby_name_for_method(@current_method)
-      warning_id = "#{method_id}#{warning_num}#{msg}"
+    def warn_no_return_codes_specified
+      warn(Apipie::Generator::Swagger::Warning::NO_RETURN_CODES_SPECIFIED_CODE)
+    end
 
-      if @issued_warnings.include?(warning_id)
-        # Already issued this warning for the current method
-        return
-      end
+    def warn_hash_without_internal_typespec(param_name)
+      warn(
+        Apipie::Generator::Swagger::Warning::HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
+        { parameter: param_name }
+      )
+    end
+
+    def warn_optional_param_in_path(param_name)
+      warn(
+        Apipie::Generator::Swagger::Warning::OPTIONAL_PARAM_IN_PATH_CODE,
+        { parameter: param_name }
+      )
+    end
+
+    def warn_optional_without_default_value(param_name)
+      warn(
+        Apipie::Generator::Swagger::Warning::OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
+        { parameter: param_name }
+      )
+    end
+
+    def warn_param_ignored_in_form_data(param_name)
+      warn(
+        Apipie::Generator::Swagger::Warning::PARAM_IGNORED_IN_FORM_DATA_CODE,
+        { parameter: param_name }
+      )
+    end
+
+    def warn_path_parameter_not_described(name, path)
+      warn(
+        Apipie::Generator::Swagger::Warning::PATH_PARAM_NOT_DESCRIBED_CODE,
+        { name: name, path: path }
+      )
+    end
 
-      print "WARNING (#{warning_num}): [#{method_id}] -- #{msg}\n"
-      @issued_warnings.push(warning_id)
-      @warnings_issued = true
+    def warn_inferring_boolean(name)
+      warn(
+        Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE,
+        { name: name }
+      )
+    end
+
+    # @param [Integer] warning_code
+    # @param [Hash] message_attributes
+    def warn(warning_code, message_attributes = {})
+      Apipie::Generator::Swagger::Warning.for_code(
+        warning_code,
+        ruby_name_for_method(@current_method),
+        message_attributes
+      ).warn_through_writer
+
+      @warnings_issued = Apipie::Generator::Swagger::WarningWriter.
+        instance.
+        issued_warnings?
     end
 
     def info(msg)
@@ -276,68 +318,21 @@ module Apipie
       http_method.downcase + path.gsub(/\//,'_').gsub(/:(\w+)/, '\1').gsub(/_$/,'')
     end
 
-    class SwaggerTypeWithFormat
-      attr_reader :str_format
-      def initialize(type, str_format)
-        @type = type
-        @str_format = str_format
-      end
-
-      def to_s
-        @type
-      end
-
-      def ==(other)
-        other.to_s == self.to_s
-      end
-    end
-
-    def lookup
-      @lookup ||= {
-        numeric: "number",
-        hash: "object",
-        array: "array",
-
-        # see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
-        integer: SwaggerTypeWithFormat.new("integer", "int32"),
-        long: SwaggerTypeWithFormat.new("integer", "int64"),
-        number: SwaggerTypeWithFormat.new("number", nil),  # here just for completeness
-        float: SwaggerTypeWithFormat.new("number", "float"),
-        double: SwaggerTypeWithFormat.new("number", "double"),
-        string: SwaggerTypeWithFormat.new("string", nil),  # here just for completeness
-        byte: SwaggerTypeWithFormat.new("string", "byte"),
-        binary: SwaggerTypeWithFormat.new("string", "binary"),
-        boolean: SwaggerTypeWithFormat.new("boolean", nil),  # here just for completeness
-        date: SwaggerTypeWithFormat.new("string", "date"),
-        dateTime: SwaggerTypeWithFormat.new("string", "date-time"),
-        password: SwaggerTypeWithFormat.new("string", "password"),
-      }
-    end
-
-
     def swagger_param_type(param_desc)
-      if param_desc.nil?
-        raise("problem")
-      end
-
-      v = param_desc.validator
-      if v.nil?
-        return "string"
+      if param_desc.blank?
+        raise ArgumentError, 'param_desc is required'
       end
 
-      if v.class == Apipie::Validator::EnumValidator || (v.respond_to?(:is_enum?) && v.is_enum?)
-        if v.values - [true, false] == [] && [true, false] - v.values == []
-          warn_inferring_boolean(param_desc.name)
-          return "boolean"
-        else
-          return "enum"
-        end
-      elsif v.class == Apipie::Validator::HashValidator
-        # pp v
-      end
+      method_id = ruby_name_for_method(@current_method)
 
+      warning = Apipie::Generator::Swagger::Warning.for_code(
+        Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE,
+        method_id,
+        { parameter: param_desc.name }
+      )
 
-      return lookup[v.expected_type.to_sym] || v.expected_type
+      Apipie::Generator::Swagger::TypeExtractor.new(param_desc.validator).
+        extract_with_warnings({ boolean: warning })
     end
 
 
@@ -473,7 +468,7 @@ module Apipie
 
       swg_param_type = swagger_param_type(param_desc)
       swagger_def[:type] = swg_param_type.to_s
-      if (swg_param_type.is_a? SwaggerTypeWithFormat) && !swg_param_type.str_format.nil?
+      if (swg_param_type.is_a? Apipie::Generator::Swagger::Type) && !swg_param_type.str_format.nil?
         swagger_def[:format] = swg_param_type.str_format
       end
 

data/lib/apipie/validator.rb

@@ -432,6 +432,10 @@ module Apipie
         "Must be a decimal number."
       end
 
+      def expected_type
+        'numeric'
+      end
+
       def self.validate(value)
         value.to_s =~ /\A^[-+]?[0-9]+([,.][0-9]+)?\Z$/
       end

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = "0.8.2"
+  VERSION = "0.9.1"
 end

data/lib/apipie-rails.rb

@@ -2,7 +2,7 @@ require 'i18n'
 require 'json'
 require 'active_support/hash_with_indifferent_access'
 
-require 'apipie/core_ext/route.rb'
+require 'apipie/core_ext/route'
 
 require "apipie/routing"
 require "apipie/markup"
@@ -12,6 +12,8 @@ require "apipie/configuration"
 require "apipie/method_description"
 require "apipie/resource_description"
 require "apipie/param_description"
+require "apipie/method_description/api"
+require "apipie/method_description/apis_service"
 require "apipie/errors"
 require "apipie/error_description"
 require "apipie/response_description"
@@ -23,3 +25,9 @@ require "apipie/railtie"
 require 'apipie/extractor'
 require "apipie/version"
 require "apipie/swagger_generator"
+require "apipie/generator/generator"
+require "apipie/generator/swagger/swagger"
+require "apipie/generator/swagger/warning"
+require "apipie/generator/swagger/warning_writer"
+require "apipie/generator/swagger/type"
+require "apipie/generator/swagger/type_extractor"

data/lib/generators/apipie/install/install_generator.rb

@@ -1,6 +1,6 @@
 module Apipie
   class InstallGenerator < ::Rails::Generators::Base
-    source_root File.expand_path("../templates", __FILE__)
+    source_root File.expand_path('templates', __dir__)
 
     class_option(:route,
                  :aliases => "-r",

data/lib/generators/apipie/views_generator.rb

@@ -1,6 +1,6 @@
 module Apipie
   class ViewsGenerator < ::Rails::Generators::Base
-    source_root File.expand_path("../../../../app/views", __FILE__)
+    source_root File.expand_path('../../../app/views', __dir__)
     desc 'Copy Apipie views to your application'
 
     def copy_views

data/lib/tasks/apipie.rake

@@ -85,7 +85,7 @@ namespace :apipie do
           counter = 1
           make_reference = true
         else
-          reference_files.sort_by! {|f| f.ctime }
+          reference_files.sort_by!(&:ctime)
           last_ref = reference_files[-1]
           print "Comparing [#{path}] to reference file: [#{last_ref.basename}]: "
           if !FileUtils.compare_file(path, last_ref)
@@ -108,7 +108,7 @@ namespace :apipie do
 
         num_refs_to_keep = 3
         if reference_files.length > num_refs_to_keep
-          (reference_files - reference_files[-num_refs_to_keep..-1]).each{|f| f.delete}
+          (reference_files - reference_files[-num_refs_to_keep..-1]).each(&:delete)
         end
       }
     end
@@ -166,10 +166,10 @@ namespace :apipie do
   def renderer
     return @apipie_renderer if @apipie_renderer
 
-    base_paths = [File.expand_path("../../../app/views/apipie/apipies", __FILE__)]
+    base_paths = [File.expand_path('../../app/views/apipie/apipies', __dir__)]
     base_paths.unshift("#{Rails.root}/app/views/apipie/apipies") if File.directory?("#{Rails.root}/app/views/apipie/apipies")
 
-    layouts_paths = [File.expand_path("../../../app/views/layouts", __FILE__)]
+    layouts_paths = [File.expand_path('../../app/views/layouts', __dir__)]
     layouts_paths.unshift("#{Rails.root}/app/views/layouts") if File.directory?("#{Rails.root}/app/views/layouts/apipie")
 
     if ActionView::Base.respond_to?(:with_empty_template_cache) && ActionView::Base.respond_to?(:with_view_paths)

data/spec/controllers/apipies_controller_spec.rb

@@ -253,7 +253,7 @@ describe Apipie::ApipiesController do
     let(:cache_dir) { File.join(Rails.root, "tmp", "apipie-cache") }
 
     before do
-      FileUtils.rm_r(cache_dir) if File.exists?(cache_dir)
+      FileUtils.rm_r(cache_dir) if File.exist?(cache_dir)
       FileUtils.mkdir_p(File.join(cache_dir, "apidoc", "v1", "resource"))
       File.open(File.join(cache_dir, "apidoc", "v1.html"), "w") { |f| f << "apidoc.html cache v1" }
       File.open(File.join(cache_dir, "apidoc", "v2.html"), "w") { |f| f << "apidoc.html cache v2" }
@@ -272,7 +272,7 @@ describe Apipie::ApipiesController do
       Apipie.configuration.use_cache = false
       Apipie.configuration.default_version = @orig_version
       Apipie.configuration.cache_dir = @orig_cache_dir
-      # FileUtils.rm_r(cache_dir) if File.exists?(cache_dir)
+      # FileUtils.rm_r(cache_dir) if File.exist?(cache_dir)
     end
 
     it "uses the file in cache dir instead of generating the content on runtime" do

data/spec/controllers/users_controller_spec.rb

@@ -51,7 +51,7 @@ describe UsersController do
       expect(subject._params_args.count).to eq(2)
       name, type, options = subject._params_args.first
       expect(name).to eq(:id)
-      expect(type).to eq(Fixnum)
+      expect(type).to eq(Integer)
       expect(options).to eq({:required=>false, :desc=>"User ID"})
     end
   end

data/spec/dummy/Rakefile

@@ -1,7 +1,7 @@
 # Add your own tasks in files placed in lib/tasks ending in .rake,
 # for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
 
-require File.expand_path('../config/application', __FILE__)
+require File.expand_path('config/application', __dir__)
 require 'rake'
 
 Dummy::Application.load_tasks

data/spec/dummy/app/controllers/users_controller.rb

@@ -4,7 +4,7 @@ class UsersController < ApplicationController
     short 'Site members'
     path '/users'
     formats ['json']
-    param :id, Fixnum, :desc => "User ID", :required => false
+    param :id, Integer, :desc => "User ID", :required => false
     param :legacy_param, Hash, :desc => 'Deprecated parameter not documented', :show => false, :required => false do
       param :resource_param, Hash, :desc => 'Param description for all methods' do
         param :ausername, String, :desc => "Username for login", :required => true

data/spec/dummy/components/test_engine/test_engine.gemspec

@@ -1,4 +1,4 @@
-$:.push File.expand_path('../lib', __FILE__)
+$:.push File.expand_path('lib', __dir__)
 
 # Describe your gem and declare its dependencies:
 Gem::Specification.new do |s|

data/spec/dummy/config/application.rb

@@ -1,4 +1,4 @@
-require File.expand_path('../boot', __FILE__)
+require File.expand_path('boot', __dir__)
 
 require "action_controller/railtie"
 require "action_view/railtie"

data/spec/dummy/config/boot.rb

@@ -1,5 +1,5 @@
 require 'rubygems'
-gemfile = File.expand_path('../../../../Gemfile', __FILE__)
+gemfile = File.expand_path('../../../Gemfile', __dir__)
 
 if File.exist?(gemfile)
   ENV['BUNDLE_GEMFILE'] = gemfile
@@ -7,4 +7,4 @@ if File.exist?(gemfile)
   Bundler.setup
 end
 
-$:.unshift File.expand_path('../../../../lib', __FILE__)
+$:.unshift File.expand_path('../../../lib', __dir__)

data/spec/dummy/config/environment.rb

@@ -2,7 +2,7 @@
 # ENV['RAILS_RELATIVE_URL_ROOT'] = '/relative/path'
 
 # Load the rails application
-require File.expand_path('../application', __FILE__)
+require File.expand_path('application', __dir__)
 
 # Initialize the rails application
 Dummy::Application.initialize!

data/spec/dummy/config/initializers/apipie.rb

@@ -23,7 +23,7 @@ Apipie.configure do |config|
   #     rake apipie:cache
   #
   config.use_cache = Rails.env.production?
-  # config.cache_dir = File.join(Rails.root, "public", "apipie-cache") # optional
+  config.cache_dir = File.join(Rails.root, "tmp", "apipie-cache") # optional
 
   # set to enable/disable reloading controllers (and the documentation with it),
   # by default enabled in development
@@ -89,7 +89,7 @@ class Apipie::Validator::IntegerValidator < Apipie::Validator::BaseValidator
   end
 
   def self.build(param_description, argument, options, block)
-    if argument == Integer || argument == Fixnum
+    if argument == Integer
       self.new(param_description, argument)
     end
   end

data/spec/dummy/config/routes.rb

@@ -11,6 +11,7 @@ Dummy::Application.routes.draw do
         end
       end
       resources :concerns, :only => [:index, :show]
+      get '/:resource_id/:custom_subst' => 'concerns#custom'
       namespace :files do
         get '/*file_path', format: false, :action => 'download'
       end

data/spec/dummy/config.ru

@@ -1,4 +1,4 @@
 # This file is used by Rack-based servers to start the application.
 
-require ::File.expand_path('../config/environment',  __FILE__)
+require ::File.expand_path('config/environment',  __dir__)
 run Dummy::Application

data/spec/dummy/script/rails

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # This command will automatically be run when you run "rails" with Rails 3 gems installed from the root of your application.
 
-APP_PATH = File.expand_path('../../config/application',  __FILE__)
-require File.expand_path('../../config/boot',  __FILE__)
+APP_PATH = File.expand_path('../config/application',  __dir__)
+require File.expand_path('../config/boot',  __dir__)
 require 'rails/commands'

data/spec/lib/application_spec.rb

@@ -27,7 +27,7 @@ describe Apipie::Application do
       end
 
       context "with an undefined base url" do
-        before {allow(Apipie.app).to receive(:get_base_url) { nil }}
+        before {allow(Apipie.app).to receive(:get_base_url).and_return(nil)}
 
         it "should not raise an error" do
           expect { Apipie.get_resource_name(Api::V2::ArchitecturesController) }.

data/spec/lib/extractor/writer_spec.rb

@@ -6,7 +6,8 @@ describe Apipie::Extractor::Writer do
   let(:writer_class) { Apipie::Extractor::Writer }
   let(:writer) { writer_class.new(collector) }
   let(:test_examples_file) { File.join(Rails.root, "doc", "apipie_examples_test.json") }
-  let(:records) { {
+  let(:records) {
+    {
     "concern_resources#show" =>
       [{
         :controller=>ConcernsController,
@@ -31,7 +32,8 @@ describe Apipie::Extractor::Writer do
       }]
     }
   }
-  let(:loaded_records) { {
+  let(:loaded_records) {
+    {
     "concern_resources#show" =>
       [{
         "verb"=>:GET,
@@ -57,16 +59,16 @@ describe Apipie::Extractor::Writer do
     }
   }
 
-  context 'with doc_path overriden in configuration' do
+  context 'with doc_path overridden in configuration' do
     around(:each) do |example|
       standard_path = Apipie.configuration.doc_path
-      Apipie.configuration.doc_path = 'user_specified_doc_path'
+      Apipie.configuration.doc_path = 'tmp/user_specified_doc_path'
       example.run
       Apipie.configuration.doc_path = standard_path
     end
 
     it 'should use the doc_path specified in configuration' do
-      expect(writer_class.examples_file).to eql(File.join(Rails.root, 'user_specified_doc_path', 'apipie_examples.json'))
+      expect(writer_class.examples_file).to eql(File.join(Rails.root, 'tmp', 'user_specified_doc_path', 'apipie_examples.json'))
     end
   end
 
@@ -104,7 +106,7 @@ describe Apipie::Extractor::Writer do
     end
 
     after do
-      File.unlink(test_examples_file) if File.exists?(test_examples_file)
+      File.unlink(test_examples_file) if File.exist?(test_examples_file)
     end
   end
 end

data/spec/lib/generator/swagger/type_extractor_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+describe Apipie::Generator::Swagger::TypeExtractor do
+  let(:validator) {}
+  let(:extractor) { described_class.new(validator) }
+
+  describe '#extarct_with_warnings' do
+    let(:warnings) { {} }
+
+    before { Apipie.configuration.swagger_suppress_warnings = false }
+
+    subject { extractor.extract_with_warnings(warnings) }
+
+    it { is_expected.to eq(Apipie::Generator::Swagger::TypeExtractor::TYPES[:string]) }
+
+    context "when enum validator is used" do
+      let(:enum_values) { ["Name"] }
+
+      context "of type Apipie::Validator::EnumValidator" do
+        let(:validator) { Apipie::Validator::EnumValidator.new(nil, enum_values) }
+
+        it { is_expected.to eq("enum") }
+      end
+
+      context "that responds to is_enum?" do
+        let(:validator) do
+          Apipie::ResponseDescriptionAdapter::PropDesc::Validator.new('some-type', enum_values)
+        end
+
+        it 'returns an enum type' do
+          expect(subject).to eq(Apipie::Generator::Swagger::TypeExtractor::TYPES[:enum])
+        end
+
+        context 'and has `true`, `false` as values' do
+          let(:param_description_name) { :visible }
+          let(:enum_values) { [true, false] }
+
+          it 'returns a boolean type' do
+            expect(subject).to eq(Apipie::Generator::Swagger::TypeExtractor::TYPES[:boolean])
+          end
+
+          context 'and a boolean warning is passed' do
+            let(:boolean_warning) do
+              Apipie::Generator::Swagger::Warning.for_code(
+                Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE,
+                'SampleController#action',
+                { parameter: 'some-param' }
+              )
+            end
+
+            let(:warnings) { { boolean: boolean_warning } }
+
+            it 'outputs the warning' do
+              expect { subject }.to output(boolean_warning.warning_message).to_stderr
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/lib/generator/swagger/warning_spec.rb

@@ -0,0 +1,51 @@
+require "spec_helper"
+
+describe Apipie::Generator::Swagger::Warning do
+  let(:code) { Apipie::Generator::Swagger::Warning::MISSING_METHOD_SUMMARY_CODE }
+  let(:method_id) { 'Examples#index' }
+  let(:info_message) { 'Something went wrong' }
+
+  let(:warning) { described_class.new(code, info_message, method_id) }
+
+  describe '#id' do
+    subject { warning.id }
+
+    it { is_expected.to eq("#{method_id}#{code}#{info_message}") }
+  end
+
+  describe '#warning_message' do
+    subject { warning.warning_message }
+
+    it { is_expected.to eq("WARNING (#{code}): [#{method_id}] -- #{info_message}") }
+  end
+
+  describe '#warn' do
+    subject { warning.warn }
+
+    it 'outputs the warning' do
+      expect { subject }.to output(warning.warning_message).to_stderr
+    end
+  end
+
+  describe '#warn_through_writer' do
+    subject { warning.warn }
+
+    it 'outputs the warning' do
+      expect { subject }.to output(warning.warning_message).to_stderr
+    end
+  end
+
+  describe '.for_code' do
+    subject { described_class.for_code(code, method_id) }
+
+    it { is_expected.to be_an_instance_of(described_class)}
+
+    context 'when code is invalid' do
+      let(:code) { 12345 }
+
+      it 'raises an argument error' do
+        expect { subject }.to raise_error(ArgumentError)
+      end
+    end
+  end
+end

data/spec/lib/generator/swagger/warning_writer_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+describe Apipie::Generator::Swagger::WarningWriter do
+  let(:writer) { described_class.clone.instance }
+
+  let(:warning) do
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE,
+      'SampleController#action',
+      { parameter: 'some-param' }
+    )
+  end
+
+  before do
+    Apipie.configuration.swagger_suppress_warnings = false
+    Singleton.__init__(described_class)
+  end
+
+  describe '#warn' do
+    subject { writer.warn(warning) }
+
+    it 'outputs the warning' do
+      expect { subject }.to output(warning.warning_message).to_stderr
+    end
+
+    context 'when Apipie.configuration.swagger_suppress_warnings is true' do
+      before { Apipie.configuration.swagger_suppress_warnings = true }
+
+      it { is_expected.to be_falsey }
+    end
+
+    context 'when Apipie.configuration.swagger_suppress_warnings includes warning code' do
+      before do
+        Apipie.configuration.swagger_suppress_warnings =
+          Array(Apipie::Generator::Swagger::Warning::INFERRING_BOOLEAN_CODE)
+      end
+
+      it { is_expected.to be_falsey }
+    end
+
+    context 'when a warning already been logged' do
+      before { writer.warn(warning) }
+
+      it { is_expected.to be_falsey }
+    end
+  end
+
+  describe '#issued_warnings?' do
+    subject { writer.issued_warnings? }
+
+    it { is_expected.to be_falsey }
+
+    context 'when a warning already been logged' do
+      before { writer.warn(warning) }
+
+      it { is_expected.to be_truthy }
+    end
+  end
+end