apipie-rails 1.3.0 → 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
@@ -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/extractor/writer.rb

@@ -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/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/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
 

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

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 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/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

@@ -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/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 }

data/spec/lib/apipie/generator/swagger/method_description/response_service_spec.rb

@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+describe Apipie::Generator::Swagger::MethodDescription::ResponseService do
+  let(:http_method) { nil }
+  let(:language) { :en }
+  let(:dsl_data) { ActionController::Base.send(:_apipie_dsl_data_init) }
+
+  let(:method_description) do
+    Apipie::Generator::Swagger::MethodDescription::Decorator.new(
+      Apipie::MethodDescription.new(
+        'create',
+        Apipie::ResourceDescription.new(ApplicationController, 'pets'),
+        dsl_data
+      )
+    )
+  end
+
+  let(:returns) { [] }
+
+  let(:service) do
+    described_class.new(
+      method_description,
+      http_method: http_method,
+      language: language
+    )
+  end
+
+  describe '#call' do
+    describe 'headers' do
+      subject(:headers) { service.call[status_code][:headers] }
+
+      let(:status_code) { 200 }
+
+      it { is_expected.to be_blank }
+
+      context 'when headers exists' do
+        let(:dsl_data) { super().merge({ returns: returns }) }
+        let(:returns) { { status_code => [{}, nil, returns_dsl, nil] } }
+
+        let(:returns_dsl) do
+          proc do
+            header 'link', String, 'Relative links'
+            header 'Current-Page', Integer, 'The current page'
+          end
+        end
+
+        it 'returns the correct format headers' do
+          expect(headers).to eq({
+                                  'link' => {
+                                    description: 'Relative links',
+                                    type: 'string'
+                                  },
+                                  'Current-Page' => {
+                                    description: 'The current page',
+                                    type: 'integer'
+                                  }
+                                })
+        end
+      end
+    end
+  end
+end

data/spec/lib/apipie/generator/swagger/param_description/builder_spec.rb

@@ -118,7 +118,7 @@ describe Apipie::Generator::Swagger::ParamDescription::Builder do
           { required: false, default_value: nil }
         end
 
-        it 'will not warn' do
+        it 'does not warn' do
           expect { subject }.not_to output(
             /is optional but default value is not specified/
           ).to_stderr
@@ -130,7 +130,7 @@ describe Apipie::Generator::Swagger::ParamDescription::Builder do
           { required: false, default_value: 123 }
         end
 
-        it 'will not warn' do
+        it 'does not warn' do
           expect { subject }.not_to output(
             /is optional but default value is not specified/
           ).to_stderr

data/spec/lib/apipie/param_description_spec.rb

@@ -21,7 +21,7 @@ describe Apipie::ParamDescription do
 
     it "should return the metadata" do
       meta = {
-        :lenght => 32,
+        :length => 32,
         :weight => '830g'
       }
       param = Apipie::ParamDescription.new(method_desc, :some_param, String, :meta => meta)

data/spec/lib/apipie/response_description/response_object_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe Apipie::ResponseDescription::ResponseObject do
+  describe '#header' do
+    let(:response_object) { described_class.new(nil, nil, nil, nil) }
+    let(:name) { 'Current-Page' }
+    let(:description) { 'The current page in the pagination' }
+
+    before { response_object.header(name, String, description) }
+
+    it 'adds it to the headers' do
+      expect(response_object.headers).to(
+        contain_exactly({
+                          name: name,
+                          description: description,
+                          validator: 'string',
+                          options: {}
+                        })
+      )
+    end
+  end
+end

data/spec/lib/apipie/response_description_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe Apipie::ResponseDescription do
+  let(:resource_description) do
+    Apipie::ResourceDescription.new(PetsController, 'pets')
+  end
+
+  let(:method_description) do
+    Apipie::MethodDescription.new(
+      'create',
+      resource_description,
+      ActionController::Base.send(:_apipie_dsl_data_init)
+    )
+  end
+
+  let(:response_description_dsl) { proc {} }
+  let(:options) { {} }
+
+  let(:response_description) do
+    described_class.new(
+      method_description,
+      204,
+      options,
+      PetsController,
+      response_description_dsl,
+      nil
+    )
+  end
+
+  describe '#to_json' do
+    let(:to_json) { response_description.to_json }
+
+    describe 'headers' do
+      subject(:headers) { to_json[:headers] }
+
+      it { is_expected.to be_blank }
+
+      context 'when response has headers' do
+        let(:response_description_dsl) do
+          proc do
+            header 'Current-Page', Integer, 'The current page in the pagination', required: true
+          end
+        end
+
+        it 'returns the header' do
+          expect(headers).to contain_exactly({
+                                               name: 'Current-Page',
+                                               description: 'The current page in the pagination',
+                                               validator: 'integer',
+                                               options: { required: true }
+                                             })
+        end
+      end
+    end
+  end
+end

data/spec/lib/swagger/swagger_dsl_spec.rb

@@ -283,7 +283,7 @@ describe "Swagger Responses" do
         expect(schema).to have_field(:pet_id, 'number', {:description => 'id of pet'})
         expect(schema).to have_field(:pet_name, 'string', {:description => 'Name of pet', :required => false})
         expect(schema).to have_field(:animal_type, 'string', {:description => 'Type of pet', :enum => %w[dog cat iguana kangaroo]})
-        expect(schema).not_to have_field(:partial_match_allowed, 'boolean', {:required => false})
+        expect(schema).not_to have_field(:partial_match_allowed, 'boolean', {:required => false}) # rubocop:disable Capybara/NegationMatcher
       end
 
       it "creates a swagger definition with all input parameters" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apipie-rails
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Pavel Pokorny
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-19 00:00:00.000000000 Z
+date: 2024-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -215,7 +215,7 @@ files:
 - MIT-LICENSE
 - NOTICE
 - PROPOSAL_FOR_RESPONSE_DESCRIPTIONS.md
-- README.rst
+- README.md
 - Rakefile
 - apipie-rails.gemspec
 - app/controllers/apipie/apipies_controller.rb
@@ -419,6 +419,7 @@ files:
 - spec/lib/apipie/generator/swagger/context_spec.rb
 - spec/lib/apipie/generator/swagger/method_description/api_schema_service_spec.rb
 - spec/lib/apipie/generator/swagger/method_description/response_schema_service_spec.rb
+- spec/lib/apipie/generator/swagger/method_description/response_service_spec.rb
 - spec/lib/apipie/generator/swagger/operation_id_spec.rb
 - spec/lib/apipie/generator/swagger/param_description/builder_spec.rb
 - spec/lib/apipie/generator/swagger/param_description/composite_spec.rb
@@ -442,6 +443,8 @@ files:
 - spec/lib/apipie/param_description_spec.rb
 - spec/lib/apipie/param_group_spec.rb
 - spec/lib/apipie/resource_description_spec.rb
+- spec/lib/apipie/response_description/response_object_spec.rb
+- spec/lib/apipie/response_description_spec.rb
 - spec/lib/apipie/response_does_not_match_swagger_schema_spec.rb
 - spec/lib/apipie/swagger_generator_spec.rb
 - spec/lib/apipie/validator_spec.rb
@@ -454,9 +457,12 @@ files:
 - spec/support/custom_bool_validator.rb
 - spec/support/rake.rb
 - spec/test_engine/memes_controller_spec.rb
-homepage: http://github.com/Apipie/apipie-rails
+homepage: https://github.com/Apipie/apipie-rails
 licenses: []
-metadata: {}
+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
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -472,7 +478,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Rails REST API documentation tool