apipie-rails 1.3.0 → 1.4.1

data/apipie-rails.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.version     = Apipie::VERSION
   s.authors     = ["Pavel Pokorny","Ivan Necas"]
   s.email       = ["pajkycz@gmail.com", "inecas@redhat.com"]
-  s.homepage    = "http://github.com/Apipie/apipie-rails"
+  s.homepage    = "https://github.com/Apipie/apipie-rails"
   s.summary     = %q{Rails REST API documentation tool}
   s.description = %q{Rails REST API documentation tool}
   s.required_ruby_version = '>= 2.6.0'
@@ -17,6 +17,12 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.require_paths = ["lib"]
 
+  s.metadata = {
+    "bug_tracker_uri" => "https://github.com/Apipie/apipie-rails/issues",
+    "changelog_uri" => "https://github.com/Apipie/apipie-rails/blob/master/CHANGELOG.md",
+    "source_code_uri" => "https://github.com/Apipie/apipie-rails"
+  }
+
   s.add_dependency "actionpack", ">= 5.0"
   s.add_dependency "activesupport", ">= 5.0"
 
@@ -32,6 +38,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rubocop-rails'
   s.add_development_dependency 'rubocop-rspec'
   s.add_development_dependency 'rubocop-performance'
+  s.add_development_dependency 'rubocop-rspec_rails' if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.7")
   s.add_development_dependency "simplecov"
   s.add_development_dependency "sqlite3"
 end

data/app/views/apipie/apipies/_method_detail.erb

@@ -55,6 +55,8 @@
         <%= render(:partial => "params", :locals => {:params => item[:returns_object]}) %>
       </tbody>
     </table>
+
+    <%= render(:partial => "headers", :locals => {:headers => item[:headers], :h_level => h_level+2 }) %>
   <% end %>
 <% end %>
 

data/app/views/apipie/apipies/_params.html.erb

@@ -15,6 +15,7 @@
       <small>
         <%= param[:required] ? t('apipie.required') : t('apipie.optional') %>
         <%= param[:allow_nil] ? ', '+t('apipie.nil_allowed') : '' %>
+        <%= param[:allow_blank] ? ', '+t('apipie.blank_allowed') : '' %>
       </small>
     </td>
     <td>

data/app/views/apipie/apipies/_params_plain.html.erb

@@ -9,6 +9,7 @@
       <small>
         <%= param[:required] ? t('apipie.required') : t('apipie.optional') %>
         <%= param[:allow_nil] ? ', '+t('apipie.nil_allowed') : '' %>
+        <%= param[:allow_blank] ? ', '+t('apipie.blank_allowed') : '' %>
         <% if param[:validator] %>
           [ <%= Apipie.markup_to_html(param[:validator]).html_safe %> ]
         <% end %>

data/config/locales/en.yml

@@ -15,6 +15,7 @@ en:
     required: required
     optional: optional
     nil_allowed: nil allowed
+    blank_allowed: blank allowed
     param_name: Param name
     params: Params
     examples: Examples

data/config/locales/ko.yml

@@ -15,6 +15,7 @@ ko:
     required: 필수
     optional: 옵션
     nil_allowed: nil 허용
+    blank_allowed: blank 허용
     param_name: Param 이름
     params: Params
     examples: 예시

data/lib/apipie/application.rb

@@ -89,7 +89,7 @@ module Apipie
 
         # we create separate method description for each version in
         # case the method belongs to more versions. We return just one
-        # becuase the version doesn't matter for the purpose it's used
+        # because the version doesn't matter for the purpose it's used
         # (to wrap the original version with validators)
         ret_method_description ||= method_description
         resource_description.add_method_description(method_description)

data/lib/apipie/dsl_definition.rb

@@ -178,7 +178,7 @@ module Apipie
       alias full_description desc
 
       # describe next method with document in given path
-      # in convension, these doc located under "#{Rails.root}/doc"
+      # in convention, these doc located under "#{Rails.root}/doc"
       # Example:
       # document "hello_world.md"
       # def hello_world
@@ -452,7 +452,7 @@ module Apipie
       include Apipie::DSL::Action
       include Apipie::DSL::Param
 
-      # defines the substitutions to be made in the API paths deifned
+      # defines the substitutions to be made in the API paths defined
       # in concerns included. For example:
       #
       # There is this method defined in concern:
@@ -472,7 +472,7 @@ module Apipie
       #
       # It has to be specified before the concern is included.
       #
-      # If not specified, the default predefined substitions are
+      # If not specified, the default predefined substitutions are
       #
       #    {:conroller_path => controller.controller_path,
       #     :resource_id  => `resource_id_from_apipie` }

data/lib/apipie/error_description.rb

@@ -5,9 +5,7 @@ module Apipie
 
     def self.from_dsl_data(args)
       code_or_options, desc, options = args
-      Apipie::ErrorDescription.new(code_or_options,
-                                   desc,
-                                   options)
+      Apipie::ErrorDescription.new(code_or_options, desc, options)
     end
 
     def initialize(code_or_options, desc = nil, options = {})
@@ -17,9 +15,13 @@ module Apipie
         @metadata = code_or_options[:meta]
         @description = code_or_options[:desc] || code_or_options[:description]
       else
-        @code = 
+        @code =
           if code_or_options.is_a? Symbol
-            Rack::Utils::SYMBOL_TO_STATUS_CODE[code_or_options]
+            begin
+              Rack::Utils.status_code(code_or_options)
+            rescue ArgumentError
+              nil
+            end
           else
             code_or_options
           end

data/lib/apipie/extractor/recorder.rb

@@ -1,7 +1,7 @@
 module Apipie
   module Extractor
     class Recorder
-      MULTIPART_BOUNDARY = 'APIPIE_RECORDER_EXAMPLE_BOUNDARY'
+      MULTIPART_BOUNDARY = 'APIPIE_RECORDER_EXAMPLE_BOUNDARY'.freeze
 
       def initialize
         @ignored_params = [:controller, :action]
@@ -14,12 +14,12 @@ module Apipie
         @params = Rack::Utils.parse_nested_query(@query)
         @params.merge!(env["action_dispatch.request.request_parameters"] || {})
         rack_input = env["rack.input"]
-        if data = parse_data(rack_input.read)
+        if data = parse_data(rack_input&.read)
           @request_data = data
         elsif form_hash = env["rack.request.form_hash"]
           @request_data = reformat_multipart_data(form_hash)
         end
-        rack_input.rewind
+        rack_input&.rewind
       end
 
       def analyse_controller(controller)

data/lib/apipie/extractor/writer.rb

@@ -324,7 +324,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} #{/^[aeiou]/.match?(name) ? 'an' : 'a'} #{name}"
                    when "index"
                      "List #{name}"
                    end
@@ -341,7 +341,7 @@ module Apipie
         params.sort_by {|n,_| n }.each do |(name, desc)|
           desc[:type] = (desc[:type] && desc[:type].first) || Object
           code << "#{indent}param"
-          if name =~ /\W/
+          if /\W/.match?(name)
             code << " :'#{name}'"
           else
             code << " :#{name}"
@@ -397,7 +397,7 @@ module Apipie
         lines_to_add = []
         block_level = 0
         ensure_line_breaks(controller_content.lines).first(action_line).reverse_each do |line|
-          if line =~ /\s*\bend\b\s*/
+          if /\s*\bend\b\s*/.match?(line)
             block_level += 1
           end
           if block_level > 0
@@ -405,10 +405,10 @@ module Apipie
           else
             added_lines << line
           end
-          if line =~ /\s*\b(module|class|def)\b /
+          if /\s*\b(module|class|def)\b /.match?(line)
             break
           end
-          next unless line =~ /do\s*(\|.*?\|)?\s*$/
+          next unless /do\s*(\|.*?\|)?\s*$/.match?(line)
           block_level -= 1
           if block_level == 0
             added_lines.concat(lines_to_add)
@@ -419,14 +419,14 @@ module Apipie
       end
 
       # this method would be totally useless unless some clever guy
-      # desided that it would be great idea to change a behavior of
+      # decided that it would be great idea to change a behavior of
       # "".lines method to not include end of lines.
       #
       # For more details:
       #   https://github.com/puppetlabs/puppet/blob/0dc44695/lib/puppet/util/monkey_patches.rb
       def ensure_line_breaks(lines)
         if lines.to_a.size > 1 && lines.first !~ /\n\Z/
-          lines.map { |l| l !~ /\n\Z/ ? (l << "\n") : l }.to_enum
+          lines.map { |l| !/\n\Z/.match?(l) ? (l << "\n") : l }.to_enum
         else
           lines
         end

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

@@ -39,7 +39,8 @@ class Apipie::Generator::Swagger::MethodDescription::ResponseService
             allow_null: false,
             http_method: @http_method,
             controller_method: @method_description
-          ).to_swagger
+          ).to_swagger,
+          headers: response_headers(response.headers)
         }.compact
       end
   end
@@ -55,4 +56,16 @@ class Apipie::Generator::Swagger::MethodDescription::ResponseService
 
     { 200 => { description: 'ok' } }
   end
+
+  # @param [Array<Hash>] headers
+  #
+  # https://swagger.io/specification/v2/#header-object
+  def response_headers(headers)
+    headers.each_with_object({}) do |header, result|
+      result[header[:name].to_s] = {
+        description: header[:description],
+        type: header[:validator]
+      }
+    end
+  end
 end

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

@@ -2,7 +2,7 @@ class Apipie::Generator::Swagger::ParamDescription::In
   IN_KEYWORD_DEFAULT_VALUES = {
     form_data: 'formData',
     query: 'query'
-  }
+  }.freeze
 
   def initialize(param_description, in_schema:, default_in_value:, http_method:)
     @param_description = param_description

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

@@ -18,7 +18,7 @@ class Apipie::Generator::Swagger::TypeExtractor
     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)

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

@@ -17,7 +17,7 @@ class Apipie::Generator::Swagger::Warning
     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",
@@ -28,7 +28,7 @@ class Apipie::Generator::Swagger::Warning
     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
 

data/lib/apipie/helpers.rb

@@ -27,7 +27,7 @@ module Apipie
       end
       path = path.sub(%r{^/},"")
       ret = "#{@url_prefix}/#{path}"
-      ret.insert(0,"/") unless ret =~ %r{\A[./]}
+      ret.insert(0,"/") unless %r{\A[./]}.match?(ret)
       ret.sub!(%r{/*\Z},"")
       ret
     end

data/lib/apipie/param_description.rb

@@ -245,7 +245,7 @@ module Apipie
 
     # makes modification that are based on the action that the param
     # is defined for. Typical for required and allow_nil variations in
-    # crate/update actions.
+    # create/update actions.
     def action_awareness
       if action_aware?
         if !@options.key?(:allow_nil)

data/lib/apipie/response_description.rb

@@ -6,6 +6,7 @@ module Apipie
       include Apipie::DSL::Param
 
       attr_accessor :additional_properties, :typename
+      attr_reader :headers
 
       def initialize(method_description, scope, block, typename)
         @method_description = method_description
@@ -13,6 +14,7 @@ module Apipie
         @param_group = {scope: scope}
         @additional_properties = false
         @typename = typename
+        @headers = []
 
         self.instance_exec(&block) if block
 
@@ -43,6 +45,18 @@ module Apipie
         end
       end
 
+      # @param [String] header_name
+      # @param [String, symbol, Class] validator
+      # @param [String] description
+      # @param [Hash] options
+      def header(header_name, validator, description, options = {})
+        @headers << {
+          name: header_name,
+          validator: validator.to_s.downcase,
+          description: description,
+          options: options
+        }
+      end
     end
   end
 
@@ -64,15 +78,6 @@ module Apipie
                                       adapter)
     end
 
-    def is_array?
-      @is_array_of != false
-    end
-
-    def typename
-      @response_object.typename
-    end
-
-
     def initialize(method_description, code, options, scope, block, adapter)
 
       @type_ref = options[:param_group]
@@ -83,11 +88,16 @@ module Apipie
 
       @method_description = method_description
 
-      if code.is_a? Symbol
-        @code = Rack::Utils::SYMBOL_TO_STATUS_CODE[code]
-      else
-        @code = code
-      end
+      @code =
+        if code.is_a? Symbol
+          begin
+            Rack::Utils.status_code(code)
+          rescue ArgumentError
+            nil
+          end
+        else
+          code
+        end
 
       @description = options[:desc]
       if @description.nil?
@@ -105,6 +115,14 @@ module Apipie
       @response_object.additional_properties ||= options[:additional_properties]
     end
 
+    def is_array?
+      @is_array_of != false
+    end
+
+    def typename
+      @response_object.typename
+    end
+
     def param_description
       nil
     end
@@ -118,6 +136,17 @@ module Apipie
     end
     alias allow_additional_properties additional_properties
 
+    # @return [Array<Hash>]
+    def headers
+      # TODO: Support headers for Apipie::ResponseDescriptionAdapter
+      if @response_object.is_a?(Apipie::ResponseDescriptionAdapter)
+        return []
+      end
+
+      @response_object.headers
+    end
+
+    # @return [Hash{Symbol->TrueClass | FalseClass}]
     def to_json(lang = nil)
       {
           :code => code,
@@ -125,6 +154,7 @@ module Apipie
           :is_array => is_array?,
           :returns_object => params_ordered.map{ |param| param.to_json(lang).tap{|h| h.delete(:validations) }}.flatten,
           :additional_properties => additional_properties,
+          :headers => headers
       }
     end
   end

data/lib/apipie/response_description_adapter.rb

@@ -11,7 +11,7 @@ module Apipie
   class ResponseDescriptionAdapter
     class Modifier
       def apply(adapter)
-        raise "Modifer subclass must implement 'apply' method"
+        raise "Modifier subclass must implement 'apply' method"
       end
     end
 

data/lib/apipie/routes_formatter.rb

@@ -1,6 +1,6 @@
 module Apipie
   class RoutesFormatter
-    API_METHODS = %w{GET POST PUT PATCH OPTIONS DELETE}
+    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.
@@ -24,7 +24,7 @@ module Apipie
       if verb.count != 1
         verb = API_METHODS.select{|defined_verb| defined_verb == rails_route.constraints[:method]}
         if verb.blank?
-          raise "Unknow verb #{rails_route.path.spec.to_s}"
+          raise "Unknown verb #{rails_route.path.spec.to_s}"
         end
       end
       verb.first

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = "1.3.0"
+  VERSION = "1.4.1".freeze
 end

data/lib/tasks/apipie.rake

@@ -70,17 +70,17 @@ namespace :apipie do
     with_loaded_documentation do
       out = ENV["OUT_REF"] || File.join(Rails.root, Apipie.configuration.doc_path, 'apidoc_ref')
       paths = generate_swagger_using_args(args, out)
-      paths.each {|path|
+      paths.each do |path|
         existing_files_in_dir = Pathname(out).children(true)
 
         make_reference = false
 
         # reference filenames have the format <basename>.<counter>.swagger_ref
-        reference_files = existing_files_in_dir.select{|f|
+        reference_files = existing_files_in_dir.select do |f|
               f.extname == '.swagger_ref' &&
               f.basename.sub_ext("").extname.delete('.').to_i > 0 &&
               f.basename.sub_ext("").sub_ext("") == path.basename.sub_ext("")
-        }
+        end
         if reference_files.empty?
           print "Reference file does not exist for [#{path}]\n"
           counter = 1
@@ -111,7 +111,7 @@ namespace :apipie do
         if reference_files.length > num_refs_to_keep
           (reference_files - reference_files[-num_refs_to_keep..-1]).each(&:delete)
         end
-      }
+      end
     end
   end
 

data/rel-eng/gem_release.ipynb

@@ -10,7 +10,7 @@
     "- push access to https://github.com/Apipie/apipie-rails\n",
     "- push access to rubygems.org for apipie-rails\n",
     "- sudo yum install python-slugify asciidoc\n",
-    "- ensure neither the `git push` or `gem push` don't require interractive auth. If you can't use api key or ssh key to auth skip these steps and run them form the shell manually\n",
+    "- ensure neither the `git push` or `gem push` don't require interactive auth. If you can't use api key or ssh key to auth skip these steps and run them form the shell manually\n",
     "- ensure all checks have passed on the branch you're about to release\n",
     "\n",
     "### Release process\n",
@@ -117,7 +117,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Run tests localy if your setup allows, otherwise ensure the HEAD is green"
+    "### Run tests locally if your setup allows, otherwise ensure the HEAD is green"
    ]
   },
   {
@@ -217,14 +217,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Manual step: Update deps in the gemspec if neccessary"
+    "#### Manual step: Update deps in the gemspec if necessary"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Check what is going to be commited"
+    "### Check what is going to be committed"
    ]
   },
   {
@@ -347,7 +347,7 @@
    "source": [
     "### Some manual steps follow to improve the UX\n",
     "\n",
-    "#### New relase on GitHub\n",
+    "#### New release on GitHub\n",
     "\n",
     "Copy the following changelog lines to the description in form on link below\n",
     "The release title is the new version."

data/spec/controllers/api/v1/architectures_controller_spec.rb

@@ -4,7 +4,7 @@ describe Api::V1::ArchitecturesController do
   describe "resource description" do
     subject { Apipie.get_resource_description(Api::V1::ArchitecturesController, "1.0") }
 
-    it "should be version 1.0" do
+    it "is version 1.0" do
       expect(subject._version).to eq('1.0')
 
       expect(Apipie.resource_descriptions['1.0'].size).to eq(2)
@@ -14,11 +14,11 @@ describe Api::V1::ArchitecturesController do
     context "there is another version" do
       let(:v2) { archv2 = Apipie.get_resource_description(Api::V2::ArchitecturesController, "2.0") }
 
-      it "should have unique doc url" do
+      it "has unique doc url" do
         expect(subject.doc_url).not_to eq(v2.doc_url)
       end
 
-      it "should have unique methods" do
+      it "has unique methods" do
         expect(subject._methods.keys).to include(:index)
         expect(v2._methods.keys).to include(:index)
         expect(subject._methods[:index]).not_to eq(v2._methods[:index])

data/spec/controllers/api/v2/nested/resources_controller_spec.rb

@@ -20,7 +20,7 @@ describe Api::V2::Nested::ResourcesController do
   describe '.get_resource_id' do
     subject { Apipie.get_resource_id(Api::V2::Nested::ResourcesController) }
 
-    it "should have resource_id set" do
+    it "has resource_id set" do
       expect(subject).to eq("resource")
     end
   end

data/spec/controllers/concerns_controller_spec.rb

@@ -7,12 +7,12 @@ describe ConcernsController do
     expect(Apipie["concern_resources#show"]).to be
   end
 
-  it "should reply to valid request" do
+  it "replies to valid request" do
     get :show, :params => { :id => '5' }, :session => { :user_id => "secret_hash" }
     assert_response :success
   end
 
-  it "should pass if required parameter is missing" do
+  it "passes if required parameter is missing" do
     expect { get :show, :params => { :id => '5' } }.not_to raise_error
   end
 

data/spec/controllers/extended_controller_spec.rb

@@ -2,13 +2,13 @@ require "spec_helper"
 
 describe ExtendedController do
 
-  it 'should include params from both original controller and extending concern' do
+  it 'includes params from both original controller and extending concern' do
     expect(Apipie["extended#create"].params.keys).to eq [:oauth, :user, :admin]
     user_param = Apipie["extended#create"].params[:user]
     expect(user_param.validator.params_ordered.map(&:name)).to eq [:name, :password, :from_concern]
   end
 
-  it 'should include updated metadata' do
+  it 'includes updated metadata' do
     expect(Apipie['extended#create'].metadata).to eq metadata: 'data'
   end
 end

data/spec/controllers/included_param_group_controller_spec.rb

@@ -5,7 +5,7 @@ describe IncludedParamGroupController do
 
   let(:dsl_data) { ActionController::Base.send(:_apipie_dsl_data_init) }
 
-  it "should not error when there is a param_group that is deeply nested in response description" do
+  it "does not error when there is a param_group that is deeply nested in response description" do
     subject = Apipie.get_resource_description(IncludedParamGroupController, Apipie.configuration.default_version)
     expect(subject._methods.keys).to include(:show)
   end