apipie-rails 0.3.2 → 0.3.3

data/CHANGELOG.md

@@ -2,6 +2,12 @@
  Changelog
 ===========
 
+v0.3.3
+------
+
+* Support for describing headers
+  [#341](https://github.com/Apipie/apipie-rails/pull/341) [@iliabylich][]
+
 v0.3.2
 ------
 
@@ -274,3 +280,4 @@ v0.0.15
 [@akenger]: https://github.com/akenger
 [@baweaver]: https://github.com/baweaver
 [@stormsilver]: https://github.com/stormsilver
+[@iliabylich]: https://github.com/iliabylich

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

@@ -0,0 +1,26 @@
+<% unless headers.blank? %>
+  <%= heading(t('apipie.headers'), h_level) %>
+  <table class='table'>
+    <thead>
+      <tr>
+        <th><%= t('apipie.header_name') %></th>
+        <th><%= t('apipie.description') %></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% headers.each do |header| %>
+        <tr>
+          <td>
+            <strong><%= header[:name] %> </strong><br>
+            <small>
+              <%= header[:options][:required] ? t('apipie.required') : t('apipie.optional') %>
+            </small>
+          </td>
+          <td>
+            <%= header[:description].html_safe %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

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

@@ -44,3 +44,5 @@
     </tbody>
   </table>
 <% end %>
+
+<%= render(:partial => "headers", :locals => {:headers => method[:headers], :h_level => h_level }) %>

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

@@ -32,6 +32,8 @@
   <%= @resource[:formats].join(', ') %>
 <% end %>
 
+<%= render(:partial => 'headers', :locals => { headers: @resource[:headers], h_level: 2 }) %>
+
 <div class='accordion' id='accordion'>
 
   <% @resource[:methods].each do |m| %>

data/config/locales/en.yml

@@ -24,4 +24,6 @@ en:
         enable_javascript_html: Please enable JavaScript to view the %{comments_href}.
         comments_powered_by_disqus: comments powered by %{disqus}
         api_documentation: API documentation
+        headers: Headers
+        header_name: Header name
 

data/lib/apipie/dsl_definition.rb

@@ -25,6 +25,7 @@ module Apipie
          :api_from_routes   => nil,
          :errors            => [],
          :params            => [],
+         :headers           => [],
          :resouce_id        => nil,
          :short_description => nil,
          :description       => nil,
@@ -129,7 +130,6 @@ module Apipie
         end
         Apipie.set_controller_versions(self, versions)
       end
-
     end
 
     module Common
@@ -268,6 +268,23 @@ module Apipie
         @method_params[method]
       end
 
+      # Describe request header.
+      #  Headers can't be validated with config.validate_presence = true
+      #
+      # Example:
+      #   header 'ClientId', "client-id"
+      #   def show
+      #     render :text => headers['HTTP_CLIENT_ID']
+      #   end
+      #
+      def header(header_name, description, options = {}) #:doc
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:headers] << {
+          name: header_name,
+          description: description,
+          options: options
+        }
+      end
     end
 
     # this describes the params, it's in separate module because it's

data/lib/apipie/method_description.rb

@@ -17,7 +17,7 @@ module Apipie
 
     end
 
-    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata, :headers
 
     def initialize(method, resource, dsl_data)
       @method = method.to_s
@@ -48,6 +48,7 @@ module Apipie
         Apipie::ParamDescription.from_dsl_data(self, args)
       end
       @params_ordered = ParamDescription.unify(@params_ordered)
+      @headers = dsl_data[:headers]
     end
 
     def id
@@ -142,7 +143,8 @@ module Apipie
         :params => params_ordered.map{ |param| param.to_json(lang) }.flatten,
         :examples => @examples,
         :metadata => @metadata,
-        :see => see.map(&:to_json)
+        :see => see.map(&:to_json),
+        :headers => headers
       }
     end
 

data/lib/apipie/resource_description.rb

@@ -9,10 +9,12 @@ module Apipie
   # name - human readable alias of resource (Articles)
   # id - resouce name
   # formats - acceptable request/response format types
+  # headers - array of headers
   class ResourceDescription
 
     attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
-      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent, :_metadata
+      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent, :_metadata,
+      :_headers
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
 
@@ -39,6 +41,7 @@ module Apipie
       @_params_args = dsl_data[:params]
       @_metadata = dsl_data[:meta]
       @_api_base_url = dsl_data[:api_base_url]
+      @_headers = dsl_data[:headers]
 
       if dsl_data[:app_info]
         Apipie.configuration.app_info[_version] = dsl_data[:app_info]
@@ -105,7 +108,8 @@ module Apipie
         :version => _version,
         :formats => @_formats,
         :metadata => @_metadata,
-        :methods => methods
+        :methods => methods,
+        :headers => _headers
       }
     end
 

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = '0.3.2'
+  VERSION = '0.3.3'
 end

data/spec/controllers/users_controller_spec.rb

@@ -35,6 +35,7 @@ describe UsersController do
       methods.keys.should include(:create)
       methods.keys.should include(:update)
       methods.keys.should include(:two_urls)
+      methods.keys.should include(:action_with_headers)
     end
 
     it "should contain info about resource" do
@@ -444,6 +445,57 @@ describe UsersController do
       a.instance_variable_get('@params_ordered').count.should == 9
     end
 
+    context 'headers' do
+      context 'for methods' do
+        let(:expected_required_header) do
+          {
+            name: :RequredHeaderName,
+            description: 'Required header description',
+            options: {
+              required: true
+            }
+          }
+        end
+
+        let(:expected_optional_header) do
+          {
+            name: :OptionalHeaderName,
+            description: 'Optional header description',
+            options: {
+              required: false
+            }
+          }
+        end
+
+        it 'contains all headers description in method doc' do
+          headers = Apipie.get_method_description(UsersController, :action_with_headers).headers
+          headers.should be_an(Array)
+
+          compare_hashes headers[0], expected_required_header
+          compare_hashes headers[1], expected_optional_header
+        end
+      end
+
+      context 'for resource' do
+        let(:expected_resource_header) do
+          {
+            name: :CommonHeader,
+            description: 'Common header description',
+            options: {
+              required: true
+            }
+          }
+        end
+
+        it 'contains all headers description in resource doc' do
+          headers = Apipie.get_resource_description(UsersController)._headers
+          headers.should be_an(Array)
+
+          compare_hashes headers[0], expected_resource_header
+        end
+      end
+    end
+
     it "should contain all api method description" do
       method_description = Apipie[UsersController, :two_urls]
       method_description.class.should be(Apipie::MethodDescription)

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

@@ -39,6 +39,7 @@ class UsersController < ApplicationController
       By default, Rails will compile each template to a method in order to render it. When you alter a template,
       Rails will check the file's modification time and recompile it in development mode.
     EOS
+    header :CommonHeader, 'Common header description', required: true
   end
 
   description <<-eos
@@ -278,4 +279,9 @@ class UsersController < ApplicationController
   def create_route
   end
 
+  api :GET, '/users/action_with_headers'
+  header :RequredHeaderName, 'Required header description', required: true
+  header :OptionalHeaderName, 'Optional header description', required: false
+  def action_with_headers
+  end
 end

metadata

@@ -1,169 +1,165 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: apipie-rails
-version: !ruby/object:Gem::Version
-  version: 0.3.2
+version: !ruby/object:Gem::Version 
+  hash: 21
   prerelease: 
+  segments: 
+  - 0
+  - 3
+  - 3
+  version: 0.3.3
 platform: ruby
-authors:
+authors: 
 - Pavel Pokorny
 - Ivan Necas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-18 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2015-03-23 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rails
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 3.0.10
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 3
+        - 0
+        - 10
         version: 3.0.10
-- !ruby/object:Gem::Dependency
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
   name: json
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
   name: rspec-rails
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.14.2
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 51
+        segments: 
+        - 2
+        - 14
+        - 2
         version: 2.14.2
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
   type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: sqlite3
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: minitest
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: maruku
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: maruku
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: RedCloth
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: RedCloth
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: rake
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :development
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: rdoc
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id009 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id009
 description: Rails REST API documentation tool
-email:
+email: 
 - pajkycz@gmail.com
 - inecas@redhat.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - .travis.yml
@@ -177,6 +173,7 @@ files:
 - NOTICE
 - README.rst
 - Rakefile
+- apipie-rails-0.3.1.gem
 - apipie-rails.gemspec
 - app/controllers/apipie/apipies_controller.rb
 - app/helpers/apipie_helper.rb
@@ -190,6 +187,7 @@ files:
 - app/public/apipie/stylesheets/bundled/bootstrap.min.css
 - app/public/apipie/stylesheets/bundled/prettify.css
 - app/views/apipie/apipies/_disqus.html.erb
+- app/views/apipie/apipies/_headers.html.erb
 - app/views/apipie/apipies/_languages.erb
 - app/views/apipie/apipies/_metadata.erb
 - app/views/apipie/apipies/_method_detail.erb
@@ -304,31 +302,41 @@ files:
 - spec/lib/validators/array_validator_spec.rb
 - spec/spec_helper.rb
 - spec/support/rake.rb
+has_rdoc: true
 homepage: http://github.com/Pajk/apipie-rails
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Rails REST API documentation tool
-test_files:
+test_files: 
 - spec/controllers/api/v1/architectures_controller_spec.rb
 - spec/controllers/api/v2/architectures_controller_spec.rb
 - spec/controllers/api/v2/nested/resources_controller_spec.rb
@@ -395,4 +403,3 @@ test_files:
 - spec/lib/validators/array_validator_spec.rb
 - spec/spec_helper.rb
 - spec/support/rake.rb
-has_rdoc: