apipie-rails 0.3.6 → 0.5.17

data/apipie-rails.gemspec

@@ -10,14 +10,13 @@ Gem::Specification.new do |s|
   s.homepage    = "http://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.0.0'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "rails", ">= 3.0.20"
-  s.add_dependency 'json'
+  s.add_dependency "rails", ">= 4.1"
   s.add_development_dependency "rspec-rails", "~> 3.0"
   s.add_development_dependency "sqlite3"
   s.add_development_dependency "minitest"
@@ -25,4 +24,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency "RedCloth"
   s.add_development_dependency "rake"
   s.add_development_dependency "rdoc"
+  s.add_development_dependency "json-schema", "~> 2.8"
 end

data/app/controllers/apipie/apipies_controller.rb

@@ -5,8 +5,8 @@ module Apipie
 
     layout Apipie.configuration.layout
 
-    around_filter :set_script_name
-    before_filter :authenticate
+    around_action :set_script_name
+    before_action :authenticate
 
     def authenticate
       if Apipie.configuration.authenticate
@@ -14,11 +14,17 @@ module Apipie
       end
     end
 
+
     def index
       params[:version] ||= Apipie.configuration.default_version
 
       get_format
 
+      if params[:type].to_s == 'swagger' && params[:format].to_s == 'json'
+        head :forbidden and return if Apipie.configuration.authorize
+        should_render_swagger = true
+      end
+
       respond_to do |format|
 
         if Apipie.configuration.use_cache?
@@ -31,9 +37,19 @@ module Apipie
         Apipie.load_documentation if Apipie.configuration.reload_controllers? || (Rails.version.to_i >= 4.0 && !Rails.application.config.eager_load)
 
         I18n.locale = @language
-        @doc = Apipie.to_json(params[:version], params[:resource], params[:method], @language)
 
-        @doc = authorized_doc
+        if should_render_swagger
+          prev_warning_value = Apipie.configuration.swagger_suppress_warnings
+          begin
+            Apipie.configuration.swagger_suppress_warnings = true
+            @doc = Apipie.to_swagger_json(params[:version], params[:resource], params[:method], @language)
+          ensure
+            Apipie.configuration.swagger_suppress_warnings = prev_warning_value
+          end
+        else
+          @doc = Apipie.to_json(params[:version], params[:resource], params[:method], @language)
+          @doc = authorized_doc
+        end
 
         format.json do
           if @doc
@@ -79,7 +95,8 @@ module Apipie
     helper_method :heading
 
     def get_language
-      lang = nil
+      return nil unless Apipie.configuration.translate
+      lang = Apipie.configuration.default_locale
       [:resource, :method, :version].each do |par|
         if params[par]
           splitted = params[par].split('.')
@@ -93,30 +110,44 @@ module Apipie
     end
 
     def authorized_doc
-
+      return if @doc.nil?
       return @doc unless Apipie.configuration.authorize
 
       new_doc = { :docs => @doc[:docs].clone }
 
-      new_doc[:docs][:resources] = @doc[:docs][:resources].select do |k, v|
-        if instance_exec(k, nil, v, &Apipie.configuration.authorize)
-          v[:methods] = v[:methods].select do |h|
-            instance_exec(k, h[:name], h, &Apipie.configuration.authorize)
-          end
-          true
-        else
-          false
+      new_doc[:docs][:resources] = if @doc[:docs][:resources].kind_of?(Array)
+        @doc[:docs][:resources].select do |resource|
+          authorize_resource(resource)
+        end
+      else
+        @doc[:docs][:resources].select do |_resource_name, resource|
+          authorize_resource(resource)
         end
       end
 
       new_doc
     end
 
+    def authorize_resource resource
+      if instance_exec(resource[:id], nil, resource, &Apipie.configuration.authorize)
+        resource[:methods] = resource[:methods].select do |m|
+          instance_exec(resource[:id], m[:name], m, &Apipie.configuration.authorize)
+        end
+        true
+      else
+        false
+      end
+    end
+
     def get_format
       [:resource, :method, :version].each do |par|
-        if params[par]
-          params[:format] = :html unless params[par].sub!('.html', '').nil?
-          params[:format] = :json unless params[par].sub!('.json', '').nil?
+        next unless params[par]
+        [:html, :json].each do |format|
+          extension = ".#{format}"
+          if params[par].include?(extension)
+            params[par] = params[par].sub(extension, '')
+            params[:format] = format
+          end
         end
       end
       request.format = params[:format] if params[:format]

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

@@ -36,5 +36,26 @@
     </tbody>
   </table>
 <% end %>
+<% unless method[:returns].blank? %>
+  <%= heading(t('apipie.returns'), h_level) %>
+  <% method[:returns].each do |item| %>
+    <%= heading("#{t('apipie.code')}: #{item[:code]}", h_level + 1) %>
+    <% if item[:description] %>
+      <%= heading("#{t('apipie.description')}:", h_level + 2) %>
+      <p><%= item[:description] %></p>
+    <% end %>
+    <table class='table'>
+      <thead>
+        <tr>
+          <th><%= t('apipie.param_name') %></th>
+          <th><%= t('apipie.description') %></th>
+        </tr>
+      </thead>
+      <tbody>
+        <%= render(:partial => "params", :locals => {:params => item[:returns_object]}) %>
+      </tbody>
+    </table>
+  <% end %>
+<% end %>
 
 <%= render(:partial => "headers", :locals => {:headers => method[:headers], :h_level => h_level }) %>

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

@@ -21,8 +21,10 @@
           <%- if param[:validator].present? %>
             <li><%= Apipie.markup_to_html(param[:validator]).html_safe %></li>
           <%- end %>
-          <%- param[:validations].each do |item| %>
-            <li><%= item.html_safe %></li>
+          <%- if param[:validations].present? %>
+            <%- param[:validations].each do |item| %>
+              <li><%= item.html_safe %></li>
+            <%- end %>
           <%- end %>
         </ul>
       <%- end %>

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

@@ -16,7 +16,11 @@
   <h2>
     <a href='<%= api[:doc_url] %><%= @doc[:link_extension] %>'>
       <%= api[:name] %>
-    </a><br>
+    </a>
+    <% if api[:deprecated] %>
+        <code>DEPRECATED</code>
+    <% end %>
+    <br>
     <small><%= api[:short_description] %></small>
   </h2>
   <table class='table'>

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

@@ -13,6 +13,9 @@
 <div class='page-header'>
   <h1>
     <%= @resource[:name] %>
+    <% if @resource[:deprecated] %>
+        <code>DEPRECATED</code>
+    <% end %>
     <br>
     <small><%= raw @resource[:short_description] %></small>
   </h1>

data/app/views/layouts/apipie/apipie.html.erb

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title><%= t('apipie.api_documentation') %></title>
+  <title><%= t('apipie.api_documentation', :default => 'Api Documentation') %></title>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <%= Apipie.include_stylesheets %>

data/config/locales/en.yml

@@ -29,3 +29,4 @@ en:
     api_documentation: API documentation
     headers: Headers
     header_name: Header name
+    code: Code

data/config/locales/fr.yml

@@ -0,0 +1,31 @@
+fr:
+  apipie:
+    resources: Ressources
+    resource: Ressource
+    description: Description
+    no_docs_found: Aucune documentation trouvée
+    no_docs_found_descr: Aucune documentation pour cette API
+    follow_instructions_html: Suivez ces %{href} sur la façon dont décrire vos controlleurs.
+    follow_instructions_href: instructions supplémentaires
+    oops: Oops!!
+    resource_not_found_html: Ressource %{resource} not found.
+    method_not_found_html: Méthode %{method} non trouvée pour la ressource %{resource}.
+    goto_homepage_html: Essayez de regarder %{href}
+    goto_homepage_href: "la page d'accueil %{app_name} API documentation homepage"
+    required: requis
+    optional: optionel
+    nil_allowed: nil autorisé
+    param_name: Nom du paramètre
+    params: Paramètres
+    examples: Exemples
+    metadata: Metadata
+    errors: Erreurs
+    error_code: Code
+    error_description: Description
+    error_metadata: Metadata
+    supported_formats: Formats supportés
+    enable_javascript_html: Activez JavaScript SVP pour afficher la %{comments_href}.
+    comments_powered_by_disqus: section commentaires par %{disqus}
+    api_documentation: documentation API
+    headers: Headers
+    header_name: Nom du header

data/config/locales/it.yml

@@ -0,0 +1,31 @@
+it:
+  apipie:
+    resources: Risorse
+    resource: Risorsa
+    description: Descrizione
+    no_docs_found: Nessuna documentazione trovata
+    no_docs_found_descr: Non abbiamo trovato nessuna documentazione per la tua API.
+    follow_instructions_html: Leggi su %{href} come descrivere i tuoi controller.
+    follow_instructions_href: ulteriori istruzioni
+    oops: Ops!!
+    resource_not_found_html: Risorsa %{resource} non trovata.
+    method_not_found_html: Metodo %{method} non trovato per la risorsa %{resource}.
+    goto_homepage_html: Prova ad andare su %{href}
+    goto_homepage_href: "%{app_name} Homepage della documentazione API"
+    required: richiesto
+    optional: opzionale
+    nil_allowed: consentito nil
+    param_name: Nome parametro
+    params: Parametri
+    examples: Esempi
+    metadata: Metadata
+    errors: Errori
+    error_code: Codice
+    error_description: Descrizione
+    error_metadata: Metadata
+    supported_formats: Formati supportati
+    enable_javascript_html: Abilita i JavaScript per vedere %{comments_href}.
+    comments_powered_by_disqus: commenti forniti da %{disqus}
+    api_documentation: Documentazione API
+    headers: Header
+    header_name: Nome Header

data/config/locales/ja.yml

@@ -0,0 +1,31 @@
+ja:
+  apipie:
+    resources: "リソース"
+    resource: "リソース"
+    description: "記述"
+    no_docs_found: "ドキュメントが見つかりませんでした。"
+    no_docs_found_descr: "あなたのAPIにあう資料が見つかりませんでした。"
+    follow_instructions_html: "コントローラーをどう説明するのか%{href}を参考にしてください。"
+    follow_instructions_href: "具体的な説明"
+    oops: "おっと！"
+    resource_not_found_html: "リソース%{resource}が見つかりませんでした。"
+    method_not_found_html: "リソース%{resource}のためのメソッド%{method}が見つかりませんでした。 ."
+    goto_homepage_html: "%{href}へ移ります。"
+    goto_homepage_href: "%{app_name}APIドキュメントのホームページ"
+    required: "必須"
+    optional: "任意"
+    nil_allowed: "nil可"
+    param_name: "パラメーター名"
+    params: "パラメーター"
+    examples: "例"
+    metadata: "メタデータ"
+    errors: "エラー"
+    error_code: "エラーコード"
+    error_description: "エラー説明"
+    error_metadata: "エラーメタデータ"
+    supported_formats: "サポートフォーマット"
+    enable_javascript_html: "%{comments_href}のJavaScriptをオンにしてください。"
+    comments_powered_by_disqus: "%{disqus}によるコメント"
+    api_documentation: "APIドキュメント"
+    headers: "ヘッダー"
+    header_name: "ヘッダー名"

data/lib/apipie/apipie_module.rb

@@ -13,6 +13,22 @@ module Apipie
     app.to_json(version, resource_name, method_name, lang)
   end
 
+  def self.to_swagger_json(version = nil, resource_name = nil, method_name = nil, lang = nil, clear_warnings=true)
+    version ||= Apipie.configuration.default_version
+    app.to_swagger_json(version, resource_name, method_name, lang, clear_warnings)
+  end
+
+  def self.json_schema_for_method_response(controller_name, method_name, return_code, allow_nulls)
+    # note: this does not support versions (only the default version is queried)!
+    version ||= Apipie.configuration.default_version
+    app.json_schema_for_method_response(version, controller_name, method_name, return_code, allow_nulls)
+  end
+
+  def self.json_schema_for_self_describing_class(cls, allow_nulls=true)
+    app.json_schema_for_self_describing_class(cls, allow_nulls)
+  end
+
+
   # all calls delegated to Apipie::Application instance
   def self.method_missing(method, *args, &block)
     app.respond_to?(method) ? app.send(method, *args, &block) : super
@@ -31,14 +47,16 @@ module Apipie
   end
 
   # get application description for given or default version
-  def self.app_info(version = nil)
-    if app_info_version_valid? version
-      Apipie.markup_to_html(self.configuration.app_info[version])
+  def self.app_info(version = nil, lang = nil)
+    info = if app_info_version_valid? version
+      translate(self.configuration.app_info[version], lang)
     elsif app_info_version_valid? Apipie.configuration.default_version
-      Apipie.markup_to_html(self.configuration.app_info[Apipie.configuration.default_version])
+      translate(self.configuration.app_info[Apipie.configuration.default_version], lang)
     else
       "Another API description"
     end
+
+    Apipie.markup_to_html info
   end
 
   def self.api_base_url(version = nil)

data/lib/apipie/application.rb

@@ -1,7 +1,7 @@
 require 'apipie/static_dispatcher'
 require 'apipie/routes_formatter'
 require 'yaml'
-require 'digest/md5'
+require 'digest/sha1'
 require 'json'
 
 module Apipie
@@ -29,7 +29,7 @@ module Apipie
       @controller_to_resource_id[controller] = resource_id
     end
 
-    def rails_routes(route_set = nil)
+    def rails_routes(route_set = nil, base_url = "")
       if route_set.nil? && @rails_routes
         return @rails_routes
       end
@@ -40,10 +40,13 @@ module Apipie
       flatten_routes = []
 
       route_set.routes.each do |route|
-        if route.app.respond_to?(:routes) && route.app.routes.is_a?(ActionDispatch::Routing::RouteSet)
-          # recursively go though the moutned engines
-          flatten_routes.concat(rails_routes(route.app.routes))
+        # This is a hack to workaround a bug in apipie with Rails 4.2.5.1 or newer. See https://github.com/Apipie/apipie-rails/issues/415
+        route_app = Rails::VERSION::STRING.to_f >= 4.2 ? route.app.app : route.app
+        if route_app.respond_to?(:routes) && route_app.routes.is_a?(ActionDispatch::Routing::RouteSet)
+          # recursively go though the mounted engines
+          flatten_routes.concat(rails_routes(route_app.routes, File.join(base_url, route.path.spec.to_s)))
         else
+          route.base_url = base_url
           flatten_routes << route
         end
       end
@@ -54,14 +57,10 @@ module Apipie
     # the app might be nested when using contraints, namespaces etc.
     # this method does in depth search for the route controller
     def route_app_controller(app, route, visited_apps = [])
-      visited_apps << app
-      if app.respond_to?(:controller)
-        return app.controller(route.defaults)
-      elsif app.respond_to?(:app) && !visited_apps.include?(app.app)
-        return route_app_controller(app.app, route, visited_apps)
+      if route.defaults[:controller]
+        controller_name = "#{route.defaults[:controller]}_controller".camelize
+        controller_name.safe_constantize
       end
-    rescue ActionController::RoutingError
-      # some errors in the routes will not stop us here: just ignoring
     end
 
     def routes_for_action(controller, method, args)
@@ -126,17 +125,17 @@ module Apipie
     # resource_description? It's used to derivate the default value of
     # versions for methods.
     def controller_versions(controller)
-      ret = @controller_versions[controller]
+      ret = @controller_versions[controller.to_s]
       return ret unless ret.empty?
       if controller == ActionController::Base || controller.nil?
         return [Apipie.configuration.default_version]
       else
-        return controller_versions(controller.superclass)
+        return controller_versions(controller.to_s.constantize.superclass)
       end
     end
 
     def set_controller_versions(controller, versions)
-      @controller_versions[controller] = versions
+      @controller_versions[controller.to_s] = versions
     end
 
     def add_param_group(controller, name, &block)
@@ -210,7 +209,7 @@ module Apipie
           return nil
         end
         resource_description = get_resource_description(resource_name)
-        if resource_description && resource_description.controller == resource
+        if resource_description && resource_description.controller.to_s == resource.to_s
           return resource_description
         end
       end
@@ -241,12 +240,13 @@ module Apipie
 
     # initialize variables for gathering dsl data
     def init_env
-      @resource_descriptions = HashWithIndifferentAccess.new { |h, version| h[version] = {} }
-      @controller_to_resource_id = {}
-      @param_groups = {}
+      @resource_descriptions ||= HashWithIndifferentAccess.new { |h, version| h[version] = {} }
+      @controller_to_resource_id ||= {}
+      @param_groups ||= {}
+      @swagger_generator = Apipie::SwaggerGenerator.new(self)
 
       # what versions does the controller belong in (specified by resource_description)?
-      @controller_versions = Hash.new { |h, controller| h[controller] = [] }
+      @controller_versions ||= Hash.new { |h, controller| h[controller.to_s] = [] }
     end
 
     def recorded_examples
@@ -258,6 +258,34 @@ module Apipie
       @recorded_examples = nil
     end
 
+    def json_schema_for_method_response(version, controller_name, method_name, return_code, allow_nulls)
+      method = @resource_descriptions[version][controller_name].method_description(method_name)
+      raise NoDocumentedMethod.new(controller_name, method_name) if method.nil?
+      @swagger_generator.json_schema_for_method_response(method, return_code, allow_nulls)
+    end
+
+    def json_schema_for_self_describing_class(cls, allow_nulls)
+      @swagger_generator.json_schema_for_self_describing_class(cls, allow_nulls)
+    end
+
+    def to_swagger_json(version, resource_name, method_name, lang, clear_warnings=false)
+      return unless valid_search_args?(version, resource_name, method_name)
+
+      # if resource_name is blank, take just resources which have some methods because
+      # we dont want to show eg ApplicationController as resource
+      # otherwise, take only the specified resource
+      _resources = resource_descriptions[version].inject({}) do |result, (k,v)|
+         if resource_name.blank?
+           result[k] = v unless v._methods.blank?
+         else
+           result[k] = v if k == resource_name
+         end
+         result
+       end
+
+      @swagger_generator.generate_from_resources(version,_resources, method_name, lang, clear_warnings)
+    end
+
     def to_json(version, resource_name, method_name, lang)
 
       return unless valid_search_args?(version, resource_name, method_name)
@@ -278,7 +306,7 @@ module Apipie
       {
         :docs => {
           :name => Apipie.configuration.app_name,
-          :info => translate(Apipie.app_info(version), lang),
+          :info => Apipie.app_info(version, lang),
           :copyright => Apipie.configuration.copyright,
           :doc_url => Apipie.full_url(url_args),
           :api_url => Apipie.api_base_url(version),
@@ -326,7 +354,7 @@ module Apipie
           all.update(version => Apipie.to_json(version))
         end
       end
-      Digest::MD5.hexdigest(JSON.dump(all_docs))
+      Digest::SHA1.hexdigest(JSON.dump(all_docs))
     end
 
     def checksum
@@ -390,9 +418,9 @@ module Apipie
     end
 
     def version_prefix(klass)
-      version = controller_versions(klass).first
+      version = controller_versions(klass.to_s).first
       base_url = get_base_url(version)
-      return "/" if base_url.nil?
+      return "/" if base_url.blank?
       base_url[1..-1] + "/"
     end
 
@@ -409,8 +437,7 @@ module Apipie
     end
 
     def load_controller_from_file(controller_file)
-      controller_class_name = controller_file.gsub(/\A.*\/app\/controllers\//,"").gsub(/\.\w*\Z/,"").camelize
-      controller_class_name.constantize
+      require_dependency controller_file
     end
 
     def ignored?(controller, method = nil)
@@ -429,10 +456,10 @@ module Apipie
     # as this would break loading of the controllers.
     def rails_mark_classes_for_reload
       unless Rails.application.config.cache_classes
-        ActionDispatch::Reloader.cleanup!
+        Rails::VERSION::MAJOR == 4 ? ActionDispatch::Reloader.cleanup! : Rails.application.reloader.reload!
         init_env
         reload_examples
-        ActionDispatch::Reloader.prepare!
+        Rails::VERSION::MAJOR == 4 ? ActionDispatch::Reloader.prepare! : Rails.application.reloader.prepare!
       end
     end
 

data/lib/apipie/configuration.rb

@@ -1,17 +1,25 @@
 module Apipie
   class Configuration
 
-    attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
+    attr_accessor :app_name, :app_info, :copyright, :compress_examples,
+      :markup, :disqus_shortname,
       :api_base_url, :doc_base_url, :required_by_default, :layout,
       :default_version, :debug, :version_in_url, :namespaced_resources,
       :validate, :validate_value, :validate_presence, :validate_key, :authenticate, :doc_path,
       :show_all_examples, :process_params, :update_checksum, :checksum_path,
       :link_extension, :record, :languages, :translate, :locale, :default_locale,
-      :persist_show_in_doc, :authorize
+      :persist_show_in_doc, :authorize,
+      :swagger_include_warning_tags, :swagger_content_type_input, :swagger_json_input_uses_refs,
+      :swagger_suppress_warnings, :swagger_api_host, :swagger_generate_x_computed_id_field,
+      :swagger_allow_additional_properties_in_response, :swagger_responses_use_refs
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
     alias_method :namespaced_resources?, :namespaced_resources
+    alias_method :swagger_include_warning_tags?, :swagger_include_warning_tags
+    alias_method :swagger_json_input_uses_refs?, :swagger_json_input_uses_refs
+    alias_method :swagger_responses_use_refs?, :swagger_responses_use_refs
+    alias_method :swagger_generate_x_computed_id_field?, :swagger_generate_x_computed_id_field
 
     # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
     #
@@ -108,7 +116,7 @@ module Apipie
     # the line above the docs.
     attr_writer :generated_doc_disclaimer
     def generated_doc_disclaimer
-      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENARATING NEXT TIME"
+      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENERATING NEXT TIME"
     end
 
     def use_disqus?
@@ -165,6 +173,14 @@ module Apipie
       @translate = lambda { |str, locale| str }
       @persist_show_in_doc = false
       @routes_formatter = RoutesFormatter.new
+      @swagger_content_type_input = :form_data  # this can be :json or :form_data
+      @swagger_json_input_uses_refs = false
+      @swagger_include_warning_tags = false
+      @swagger_suppress_warnings = false #[105,100,102]
+      @swagger_api_host = "localhost:3000"
+      @swagger_generate_x_computed_id_field = false
+      @swagger_allow_additional_properties_in_response = false
+      @swagger_responses_use_refs = true
     end
   end
 end

data/lib/apipie/core_ext/route.rb

@@ -0,0 +1,9 @@
+module Apipie
+  module BaseUrlExtension
+    attr_accessor :base_url
+  end
+end
+
+class ActionDispatch::Journey::Route
+  include Apipie::BaseUrlExtension
+end