apipie-rails 0.0.7

data/lib/apipie-rails.rb

@@ -0,0 +1,12 @@
+require "apipie/routing"
+require "apipie/markup"
+require "apipie/apipie_module"
+require "apipie/method_description"
+require "apipie/resource_description"
+require "apipie/param_description"
+require "apipie/error_description"
+require "apipie/validator"
+require "apipie/dsl_definition"
+require "apipie/railtie"
+require 'apipie/extractor'
+require "apipie/version"

data/lib/apipie/apipie_module.rb

@@ -0,0 +1,105 @@
+require "apipie/helpers"
+require "apipie/application"
+
+module Apipie
+  extend Apipie::Helpers
+
+  def self.app
+    @application ||= Apipie::Application.new
+  end
+
+  def self.to_json(resource_name = nil, method_name = nil)
+    app.to_json(resource_name, method_name)
+  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
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  class Configuration
+    attr_accessor :app_name, :app_info, :copyright, :markup,
+      :validate, :api_base_url, :doc_base_url
+
+    alias_method :validate?, :validate
+
+    # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
+    #
+    #   "#{Rails.root}/app/controllers/api/*.rb"
+    attr_accessor :api_controllers_matcher
+
+    # set to true if you want to reload the controllers at each refresh of the
+    # documentation. It requires +:api_controllers_matcher+ to be set to work
+    # properly.
+    attr_writer :reload_controllers
+
+    def reload_controllers?
+      @reload_controllers = Rails.env.development? unless defined? @reload_controllers
+      return @reload_controllers && @api_controllers_matcher
+    end
+
+    # set to true if you want to use pregenerated documentation cache and avoid
+    # generating the documentation on runtime (usefull for production
+    # environment).
+    # You can generate the cache by running
+    #
+    #     rake apipie:cache
+    attr_accessor :use_cache
+    alias_method :use_cache?, :use_cache
+
+    attr_writer :cache_dir
+    def cache_dir
+      @cache_dir ||= File.join(Rails.root, "public", "apipie-cache")
+    end
+
+    # if there is not obvious reason why the DSL should be turned on (no
+    # validations, cache turned on etc.), it's disabled to avoid unneeded
+    # allocation. It you need the DSL for other reasons, you can force the
+    # activation.
+    attr_writer :force_dsl
+    def force_dsl?
+      @force_dsl
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when extracting description form calls.
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored_by_recorder
+    def ignored_by_recorder
+      @ignored_by_recorder ||= []
+      @ignored_by_recorder.map(&:to_s)
+    end
+
+    # comment to put before docs that was generated automatically. It's used to
+    # determine if the description should be overwritten next recording.
+    # If you want to keep the documentation (prevent from overriding), remove
+    # 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"
+    end
+
+    def app_info
+      Apipie.markup_to_html(@app_info)
+    end
+
+    def initialize
+      @markup = Apipie::Markup::RDoc.new
+      @app_name = "Another API"
+      @app_info = "Another API description"
+      @copyright = nil
+      @validate = true
+      @api_base_url = ""
+      @doc_base_url = "/apipie"
+    end
+  end
+
+end

data/lib/apipie/application.rb

@@ -0,0 +1,225 @@
+require 'apipie/static_dispatcher'
+require 'yaml'
+
+module Apipie
+
+  class Application
+
+    # we need engine just for serving static assets
+    class Engine < Rails::Engine
+      initializer "static assets" do |app|
+        app.middleware.use ::Apipie::StaticDispatcher, "#{root}/app/public", Apipie.configuration.doc_base_url
+      end
+    end
+
+    attr_accessor :last_api_args, :last_errors, :last_params, :last_description, :last_examples, :last_see
+    attr_reader :method_descriptions, :resource_descriptions
+
+    def initialize
+      super
+      @method_descriptions = Hash.new
+      @resource_descriptions = Hash.new
+      clear_last
+    end
+
+    # create new method api description
+    def define_method_description(controller, method_name)
+      # create new or get existing api
+      resource_name = get_resource_name(controller)
+      key = [resource_name, method_name].join('#')
+      # add method description key to resource description
+      resource = define_resource_description(controller)
+
+      method_description = Apipie::MethodDescription.new(method_name, resource, self)
+
+      @method_descriptions[key] ||= method_description
+
+      @method_descriptions[key]
+    end
+
+    # create new resource api description
+    def define_resource_description(controller, &block)
+      resource_name = get_resource_name(controller)
+
+      # puts "defining api for #{resource_name}"
+
+      @resource_descriptions[resource_name] ||=
+        Apipie::ResourceDescription.new(controller, resource_name, &block)
+    end
+
+    def add_method_description_args(method, path, desc)
+      @last_api_args << MethodDescription::Api.new(method, path, desc)
+    end
+
+    def add_example(example)
+      @last_examples << example.strip_heredoc
+    end
+
+    # check if there is some saved description
+    def apipie_provided?
+      true unless last_api_args.blank?
+    end
+
+    # get api for given method
+    #
+    # There are two ways how this method can be used:
+    # 1) Specify both parameters
+    #   resource_name: controller class or string with resource name (plural)
+    #   method_name: name of the method (string or symbol)
+    # 2) Specify only first parameter:
+    #   resource_name: string containing both resource and method name joined
+    #   with # (eg. "users#create")
+    def get_method_description(resource_name, method_name = nil)
+      resource_name = get_resource_name(resource_name)
+      key = method_name.blank? ? resource_name : [resource_name, method_name].join('#')
+      @method_descriptions[key]
+    end
+    alias :[] :get_method_description
+
+    # get api for given resource
+    def get_resource_description(resource_name)
+      resource_name = get_resource_name(resource_name)
+
+      @resource_descriptions[resource_name]
+    end
+
+    def remove_method_description(resource_name, method_name)
+      resource_name = get_resource_name(resource_name)
+
+      @method_descriptions.delete [resource_name, method_name].join('#')
+    end
+
+    def remove_resource_description(resource_name)
+      resource_name = get_resource_name(resource_name)
+
+      @resource_descriptions.delete resource_name
+    end
+
+    # Clear all apis in this application.
+    def clear
+      @resource_descriptions.clear
+      @method_descriptions.clear
+    end
+
+    # clear all saved data
+    def clear_last
+      @last_api_args = []
+      @last_errors = []
+      @last_params = []
+      @last_description = nil
+      @last_examples = []
+      @last_see = nil
+    end
+
+    # Return the current description, clearing it in the process.
+    def get_description
+      desc = @last_description
+      @last_description = nil
+      desc
+    end
+
+    def get_errors
+      errors = @last_errors.clone
+      @last_errors.clear
+      errors
+    end
+
+    def get_api_args
+      api_args = @last_api_args.clone
+      @last_api_args.clear
+      api_args
+    end
+
+    def get_see
+      see = @last_see
+      @last_see = nil
+      see
+    end
+
+    def get_params
+      params = @last_params.clone
+      @last_params.clear
+      params
+    end
+
+    def get_examples
+      examples = @last_examples.clone
+      @last_examples.clear
+      examples
+    end
+
+    def recorded_examples
+      return @recorded_examples if @recorded_examples
+      tape_file = File.join(Rails.root,"doc","apipie_examples.yml")
+      if File.exists?(tape_file)
+        @recorded_examples = YAML.load_file(tape_file)
+      else
+        @recorded_examples = {}
+      end
+      @recorded_examples
+    end
+
+    def reload_examples
+      @recorded_examples = nil
+    end
+
+    def to_json(resource_name, method_name)
+
+      _resources = if resource_name.blank?
+        # take just resources which have some methods because
+        # we dont want to show eg ApplicationController as resource
+        resource_descriptions.inject({}) do |result, (k,v)|
+          result[k] = v.to_json unless v._methods.blank?
+          result
+        end
+      else
+        [@resource_descriptions[resource_name].to_json(method_name)]
+      end
+
+      {
+        :docs => {
+          :name => Apipie.configuration.app_name,
+          :info => Apipie.configuration.app_info,
+          :copyright => Apipie.configuration.copyright,
+          :doc_url => Apipie.full_url(""),
+          :api_url => Apipie.configuration.api_base_url,
+          :resources => _resources
+        }
+      }
+    end
+
+    def api_controllers_paths
+      Dir[Apipie.configuration.api_controllers_matcher]
+    end
+
+    def reload_documentation
+      reload_examples
+      api_controllers_paths.each do |f|
+        load_controller_from_file f
+      end
+    end
+
+    # Is there a reason to interpret the DSL for this run?
+    # with specific setting for some environment there is no reason the dsl
+    # should be interpreted (e.g. no validations and doc from cache)
+    def active_dsl?
+      Apipie.configuration.validate? || ! Apipie.configuration.use_cache? || Apipie.configuration.force_dsl?
+    end
+
+    private
+
+    def get_resource_name(klass)
+      if klass.class == String
+        klass
+      elsif klass.respond_to?(:controller_name)
+        klass.controller_name
+      end
+    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
+    end
+
+  end
+end

data/lib/apipie/client/generator.rb

@@ -0,0 +1,105 @@
+#!/bin/env ruby
+# -*- coding: utf-8 -*-
+require 'rubygems'
+require 'thor'
+require 'thor/group'
+require 'fileutils'
+require 'active_support/inflector'
+
+module Apipie
+  module Client
+
+    class Generator < Thor::Group
+      include Thor::Actions
+
+      # Define arguments and options
+      argument :name
+
+      attr_reader :doc, :resource
+
+      def initialize(*args)
+        super
+        @doc = Apipie.to_json()[:docs]
+      end
+
+      def self.source_root
+        File.expand_path("../template", __FILE__)
+      end
+
+      def self.destination_root(name)
+        File.join(FileUtils.pwd, "#{name}_client")
+      end
+
+      def self.start(client_name)
+        name = client_name.parameterize.underscore
+        super([name], :destination_root => destination_root(name))
+      end
+
+      def generate_cli
+        template("README.tt", "README")
+        template("Gemfile.tt", "Gemfile")
+        template("bin.rb.tt", "bin/#{name}_client")
+        chmod("bin/#{name}_client", 0755)
+        template("client.rb.tt", "lib/#{name}_client.rb")
+        template("base.rb.tt", "lib/#{name}_client/base.rb")
+        template("cli_command.rb.tt", "lib/#{name}_client/cli_command.rb")
+        doc[:resources].each do |key, resource|
+          @resource = resource
+          template("cli.rb.tt", "lib/#{name}_client/commands/#{resource_name}.thor")
+          template("resource.rb.tt", "lib/#{name}_client/resources/#{resource_name}.rb")
+        end
+      end
+
+      protected
+
+      def class_base
+        name.camelize
+      end
+
+      def plaintext(text)
+        text.gsub(/<.*?>/, '').gsub("\n",' ').strip
+      end
+
+      # Resource related helper methods:
+
+      def resource_name
+        resource[:name].gsub(/\s/,"_").downcase.singularize
+      end
+
+      def api(method)
+        method[:apis].first
+      end
+
+      def params_in_path(method)
+        api(method)[:api_url].scan(/:([^\/]*)/).map(&:first)
+      end
+
+      def client_args(method)
+        client_args = params_in_path(method).dup
+        client_args << "params = {}" if method[:params].any?
+        client_args
+      end
+
+      def validation_hash(method)
+        if method[:params].any? { |p| p[:params] }
+          method[:params].reduce({}) do |h, p|
+            h.update(p[:name] => (p[:params] ? p[:params].map { |pp| pp[:name] } : nil))
+          end
+        else
+          method[:params].map { |p| p[:name] }
+        end
+      end
+
+      def substituted_url(method)
+        params_in_path(method).reduce(api(method)[:api_url]) { |u, p| u.sub(":#{p}","\#{#{p}}")}
+      end
+
+      def transformation_hash(method)
+        method[:params].find_all { |p| p[:expected_type] == "hash" && !p[:params].nil? }.reduce({}) do |h, p|
+          h.update(p[:name] => p[:params].map { |pp| pp[:name] })
+        end
+      end
+    end
+
+  end
+end