apipie-rails 1.2.3 → 1.4.0

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"
 

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
@@ -242,7 +242,7 @@ module Apipie
 
               if Apipie.configuration.validate_presence?
                 Validator::BaseValidator.raise_if_missing_params do |missing|
-                  method_params.each do |_, param|
+                  method_params.each_value do |param|
                     # check if required parameters are present
                     missing << param if param.required && !params.key?(param.name)
                   end
@@ -250,7 +250,7 @@ module Apipie
               end
 
               if Apipie.configuration.validate_value?
-                method_params.each do |_, param|
+                method_params.each_value do |param|
                   # params validations
                   param.validate(params[:"#{param.name}"]) if params.key?(param.name)
                 end
@@ -267,12 +267,11 @@ module Apipie
                 end
               end
 
-              if Apipie.configuration.process_value?
-                @api_params ||= {}
-                method_params.each do |_, param|
-                  # params processing
-                  @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.key?(param.name)
-                end
+              return unless Apipie.configuration.process_value?
+              @api_params ||= {}
+              method_params.each_value do |param|
+                # params processing
+                @api_params[param.as] = param.process_value(params[:"#{param.name}"]) if params.key?(param.name)
               end
             end
           end
@@ -453,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:
@@ -473,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/errors.rb

@@ -62,7 +62,7 @@ module Apipie
     attr_accessor :value, :error
 
     def initialize(param, value, error)
-      super param
+      super(param)
       @value = value
       @error = error
     end

data/lib/apipie/extractor/collector.rb

@@ -89,7 +89,7 @@ module Apipie
       end
 
       def finalize_descriptions
-        @descriptions.each do |method, desc|
+        @descriptions.each_value do |desc|
           add_routes_info(desc)
         end
         return @descriptions

data/lib/apipie/extractor/recorder.rb

@@ -90,7 +90,7 @@ module Apipie
           lines << '' << %{... contents of "#{attrs[:name]}" ...}
         else
           # Look for subelements that contain a part.
-          attrs.each { |k,v| v.is_a?(Hash) and reformat_hash(boundary, v, lines) }
+          attrs.each_value { |v| v.is_a?(Hash) and reformat_hash(boundary, v, lines) }
         end
       end
 

data/lib/apipie/extractor/writer.rb

@@ -80,7 +80,7 @@ module Apipie
 
       def write_docs
         descriptions = @collector.finalize_descriptions
-        descriptions.each do |_, desc|
+        descriptions.each_value do |desc|
           if desc[:api].empty?
             logger.warn("REST_API: Couldn't find any path for #{desc_to_s(desc)}")
             next
@@ -419,7 +419,7 @@ 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:

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

@@ -24,7 +24,7 @@ module Apipie
               HEREDOC
             )
 
-            send("#{attribute}=", value)
+            send(:"#{attribute}=", value)
           end
 
           old_setter_method = "swagger_#{attribute}"

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

@@ -96,7 +96,7 @@ class Apipie::Generator::Swagger::MethodDescription::ParametersService
   def path_param_descriptions
     @path_param_descriptions ||= all_params
                                  .select { |k, _| @path.param?(k) }
-                                 .each { |_, desc| desc.required = true }
+                                 .each_value { |desc| desc.required = true }
                                  .values
   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/builder.rb

@@ -53,6 +53,7 @@ class Apipie::Generator::Swagger::ParamDescription::Builder
 
     definition.merge!(for_default)
     definition.merge!(for_required)
+    definition.merge!(for_example)
     definition.merge!(@description.to_hash) if @description.present?
 
     warn_optional_without_default_value(definition)
@@ -78,6 +79,14 @@ class Apipie::Generator::Swagger::ParamDescription::Builder
     }
   end
 
+  def for_example
+    return {} unless @param_description.options.key?(:example)
+
+    {
+      example: @param_description.options[:example],
+    }
+  end
+
   def required?
     required_from_path? || @param_description.required
   end

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

@@ -56,7 +56,7 @@ class Apipie::Generator::Swagger::ParamDescription::Type
 
   def for_array_type
     validator_opts = validator.param_description.options
-    items_type = validator_opts[:of].to_s || validator_opts[:array_of].to_s
+    items_type = (validator_opts[:of] || validator_opts[:array_of]).to_s
 
     if items_type == 'Hash' && params_in_body_use_reference?
       reference_name = Apipie::Generator::Swagger::OperationId.
@@ -67,7 +67,7 @@ class Apipie::Generator::Swagger::ParamDescription::Type
         '$ref' => reference_name
       }
     else
-      items = { type: 'string' }
+      items = { type: array_items_type(items_type).to_s }
     end
 
     enum = @param_description.options[:in]
@@ -80,6 +80,19 @@ class Apipie::Generator::Swagger::ParamDescription::Type
     }
   end
 
+  # @param [String] items_type
+  #
+  # @return [Apipie::Generator::Swagger::Type]
+  def array_items_type(items_type)
+    type = Apipie::Generator::Swagger::TypeExtractor::TYPES[items_type.downcase.to_sym]
+
+    if type == 'object' || type.blank?
+      Apipie::Generator::Swagger::TypeExtractor::TYPES[:string]
+    else
+      type
+    end
+  end
+
   def for_enum_type
     {
       type: 'string',

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

@@ -19,9 +19,9 @@ class Apipie::Generator::Swagger::ResourceDescriptionsCollection
 
     if method_name.present?
       resources = resources.select do |resource_description|
-        resource_description._methods.select do |method_description_name, _|
+        resource_description._methods.any? do |method_description_name, _|
           method_description_name == method_name
-        end.present?
+        end
       end
     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]
@@ -105,6 +110,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 +131,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 +149,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
 
@@ -57,7 +57,7 @@ module Apipie
         attr_reader :expected_type
 
         def [](key)
-          return self.send(key) if self.respond_to?(key.to_s)
+          self.send(key) if self.respond_to?(key.to_s)
         end
 
         def initialize(expected_type, enum_values = nil, sub_properties = nil)
@@ -102,7 +102,7 @@ module Apipie
       end
 
       def [](key)
-        return self.send(key) if self.respond_to?(key.to_s)
+        self.send(key) if self.respond_to?(key.to_s)
       end
 
       def add_sub_property(prop_desc)

data/lib/apipie/routes_formatter.rb

@@ -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/static_dispatcher.rb

@@ -4,7 +4,13 @@ module Apipie
     def initialize(root)
       @root          = root.chomp('/')
       @compiled_root = /^#{Regexp.escape(root)}/
-      @file_server   = ::Rack::File.new(@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)

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = "1.2.3"
+  VERSION = "1.4.0"
 end

data/lib/tasks/apipie.rake

@@ -186,11 +186,11 @@ namespace :apipie do
     av = renderer
     File.open(file_name, "w") do |f|
       variables.each do |var, val|
-        av.instance_variable_set("@#{var}", val)
+        av.instance_variable_set(:"@#{var}", val)
       end
       f.write av.render(
         :template => "#{template}",
-        :layout => (layout && "apipie/#{layout}"))
+        :layout => layout && "apipie/#{layout}")
     end
   end
 
@@ -259,7 +259,7 @@ namespace :apipie do
   end
 
   def generate_resource_pages(version, file_base, doc, include_json = false, lang = nil)
-    doc[:docs][:resources].each do |resource_id, _|
+    doc[:docs][:resources].each_key do |resource_id|
       resource_file_base = File.join(file_base, resource_id.to_s)
       FileUtils.mkdir_p(File.dirname(resource_file_base)) unless File.exist?(File.dirname(resource_file_base))
 

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/users_controller_spec.rb

@@ -430,7 +430,7 @@ describe UsersController do
       expect(b.full_description.length).to be > 400
     end
 
-    context "Usign routes.rb" do
+    context "Using routes.rb" do
       it "should contain basic info about method" do
         a = Apipie[UsersController, :create_route]
         expect(a.apis.count).to eq(1)

data/spec/dummy/app/controllers/api/v2/empty_middle_controller.rb

@@ -2,7 +2,7 @@ module Api
   module V2
     class EmptyMiddleController < V2::BaseController
       # This is an empty controller, used to test cases where controllers
-      # may inherit from a middle controler that does not define a resource_description,
+      # may inherit from a middle controller that does not define a resource_description,
       # but the middle controller's parent does.
 
       def inconsequential_method

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

@@ -23,7 +23,7 @@ class PetsController < ApplicationController
   #-----------------------------------------------------------
   api :GET, "/pets/:id/as_properties", "Get a pet record"
   returns :code => 200 do
-    property :pet_name, String, :desc => "Name of pet", :required => false
+    property :pet_name, String, :desc => "Name of pet", :required => false, :example => 'mypet'
     property :animal_type, %w[dog cat iguana kangaroo], :desc => "Type of pet"   # required by default, because this is a 'property'
   end
   returns :code => 404 do
@@ -63,7 +63,7 @@ class PetsController < ApplicationController
   # mixing request/response and response-only parameters
   #
   # the param_group :pet_with_id has several parameters which are
-  # not expectd in the request, but would show up in the response
+  # not expected in the request, but would show up in the response
   # and vice versa
   #-----------------------------------------------------------
   def_param_group :pet_with_id do

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

@@ -10,7 +10,7 @@ class TwitterExampleController < ApplicationController
   api :GET, '/twitter_example/lookup', 'Return up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two.'
   param :screen_name, String, :desc => 'A comma separated list of screen names, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger (up to 100 screen names) requests.'
   param :user_id, Integer, :desc => 'A comma separated list of user IDs, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger requests.'
-  param :include_entities, String, :desc => 'When set to either <code>true</code>, <code>t</code> or <code>1</code>, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.'
+  param :include_entities, String, :desc => 'When set to either <code>true</code>, <code>t</code> or <code>1</code>, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discrete structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.'
   
   description <<-EOS
     Return up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two. The author's most recent status (if the authenticating user has permission) will be returned inline.
@@ -53,8 +53,8 @@ class TwitterExampleController < ApplicationController
   api :GET, '/twitter_example/search', 'Runs a search for users similar to Find People button on Twitter.com.'
   param :q, String, :desc => 'The search query to run against people search.', :required => true
   param :page, Integer, :desc => 'Specifies the page of results to retrieve.'
-  param :per_page, Integer, :desc => 'The number of people to retrieve. Maxiumum of 20 allowed per page.'
-  param :include_entities, String, :desc => 'When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.'
+  param :per_page, Integer, :desc => 'The number of people to retrieve. Maximum of 20 allowed per page.'
+  param :include_entities, String, :desc => 'When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discrete structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.'
   description <<-EOS
     Runs a search for users similar to Find People button on Twitter.com. The results returned by people search on Twitter.com are the same as those returned by this API request. Note that unlike GET search, this method does not support any operators.
 

data/spec/lib/apipie/apipies_controller_spec.rb

@@ -188,7 +188,7 @@ describe Apipie::ApipiesController, type: :controller do
 
 
   describe "authenticate user" do
-    it "authenticate user if an authentication method is setted" do
+    it "authenticate user if an authentication method is set" do
       test = false
       Apipie.configuration.authenticate = Proc.new do
         test = true

data/spec/lib/apipie/extractor_spec.rb

@@ -2,7 +2,7 @@ require "spec_helper"
 
 describe Apipie::Extractor do
   it 'handles routes without (.:format)' do
-    Apipie::Extractor.apis_from_routes.each do |(controller, action), apis|
+    Apipie::Extractor.apis_from_routes.each_value do |apis|
       apis.each { |api| expect(api[:path]).not_to be_nil }
     end
   end

data/spec/lib/apipie/file_handler_spec.rb

@@ -15,7 +15,7 @@ describe Apipie::FileHandler do
       it { expect { file_handler.match? path }.to_not raise_error }
     end
 
-    context 'when the path contans an invalid byte sequence in UTF-8' do
+    context 'when the path contains an invalid byte sequence in UTF-8' do
       let(:path) { "%B6" }
 
       it { expect(file_handler.match? path).to be_falsy }