api_sketch 0.1.0

data/lib/api_sketch/dsl.rb

@@ -0,0 +1,213 @@
+class ApiSketch::DSL
+
+  COMPLEX_ATTRIBUTE_NAMES = [:headers, :parameters, :responses]
+
+  def initialize(definitions_dir=ApiSketch::Config[:definitions_dir])
+    @definitions_dir = definitions_dir
+  end
+
+  def init!
+    Dir.glob("#{@definitions_dir}/**/*.rb").each do |file_path|
+      puts_info("\t read: #{file_path}")
+      binding.eval(File.open(File.expand_path(file_path)).read, file_path)
+    end
+  end
+
+  class AttributeParser
+
+    def initialize(container_type, &block)
+      @attribute_values = {}
+      @container_type = container_type
+      # INFO: Such long method name is used to ensure that we are would not have such value as key at hash
+      define_singleton_method(:set_attributes_as_hash_value_format, block)
+      set_attributes_as_hash_value_format
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      @attribute_values[method_name] = arguments.first || block
+    end
+
+    def to_h
+      @attribute_values
+    end
+
+  end
+
+
+  class Attributes
+
+    TYPES = [:integer, :string, :float, :boolean, :datetime, :timestamp, :document, :array]
+
+    def initialize(container_type, &block)
+      @container_type = container_type
+      @params = []
+      define_singleton_method(:initialize_attributes, block)
+      initialize_attributes
+    end
+
+    def to_a
+      @params
+    end
+
+    def shared(name)
+      self.instance_eval(&::ApiSketch::Model::SharedBlock.find(name))
+    end
+
+    TYPES.each do |type_name|
+      define_method(type_name) do |*args, &block|
+        name = args.first
+        if @container_type == :document
+          if name.nil? || name.empty? # key name is not provided
+            raise ::ApiSketch::Error.new, "Key inside document should have name"
+          end
+        elsif @container_type == :array
+          if (!name.nil? && !name.empty?) # key name is provided
+            raise ::ApiSketch::Error.new, "Array element can't have name"
+          end
+        end
+        @params << self.class.build_by(type_name, name, &block)
+      end
+    end
+
+    class << self
+      def build_by(data_type, attribute_name, &block)
+        options = {data_type: data_type}
+        options[:name] = attribute_name if attribute_name
+        case data_type
+        when :document, :array
+          ::ApiSketch::Model::Attribute.new(::ApiSketch::DSL::ComplexAttributeParser.new(data_type, &block).to_h.merge(options))
+        else
+          ::ApiSketch::Model::Attribute.new(::ApiSketch::DSL::AttributeParser.new(data_type, &block).to_h.merge(options))
+        end
+      end
+    end
+
+  end
+
+  class ComplexAttributeParser < ApiSketch::DSL::AttributeParser
+
+    def method_missing(method_name, *arguments, &block)
+      if method_name == :content
+        @attribute_values[:content] = ApiSketch::DSL::Attributes.new(@container_type, &block).to_a
+      else
+        super(method_name, *arguments, &block)
+      end
+    end
+
+  end
+
+
+  class Headers
+
+    def initialize(&block)
+      @list = []
+      define_singleton_method(:initialize_headers_list, block)
+      initialize_headers_list
+    end
+
+    def to_a
+      @list
+    end
+
+    def add(name, &block)
+      @list << ::ApiSketch::Model::Header.new(::ApiSketch::DSL::AttributeParser.new(:document, &block).to_h.merge(name: name))
+    end
+
+  end
+
+  class Parameters
+
+    def initialize(&block)
+      @query = []
+      @body = []
+      @query_container_type = nil
+      @body_container_type = nil
+      define_singleton_method(:initialize_parameters_list, block)
+      initialize_parameters_list
+    end
+
+    def to_h
+      {
+        query: @query,
+        body: @body,
+        query_container_type: @query_container_type,
+        body_container_type: @body_container_type
+      }
+    end
+
+    def query(container_type, &block)
+      @query_container_type = container_type
+      @query += ::ApiSketch::DSL::Attributes.new(container_type, &block).to_a
+    end
+
+    def body(container_type, &block)
+      @body_container_type = container_type
+      @body += ::ApiSketch::DSL::Attributes.new(container_type, &block).to_a
+    end
+
+  end
+
+  class Responses
+
+    def initialize(&block)
+      @list = []
+      define_singleton_method(:initialize_responses_list, block)
+      initialize_responses_list
+    end
+
+    def to_a
+      @list
+    end
+
+    def context(name, &block)
+      attributes = ::ApiSketch::DSL::AttributeParser.new(:root, &block).to_h
+      if attributes[:parameters]
+        params = ::ApiSketch::DSL::Parameters.new(&attributes[:parameters]).to_h
+        attributes[:parameters] = ::ApiSketch::Model::Parameters.new(params)
+      end
+      @list << ::ApiSketch::Model::Response.new(attributes.merge(name: name))
+    end
+
+  end
+
+  def shared_block(name, block)
+    ::ApiSketch::Model::SharedBlock.add(name, block)
+  end
+
+  def resource(name, &block)
+    attributes = get_attrs(name, &block)
+
+    COMPLEX_ATTRIBUTE_NAMES.each do |attribute_name|
+      block_value = attributes[attribute_name]
+      attributes[attribute_name] = get_complex_attribute(attribute_name, &block_value) if block_value
+    end
+
+    # Assign resource namespace
+    attributes[:namespace] ||= block.source_location[0].gsub(definitions_dir, "").gsub(".rb", "").split("/").reject { |ns| ns.nil? || ns == "" }.join("/")
+
+    ::ApiSketch::Model::Resource.create(attributes)
+  end
+
+
+  private
+    def definitions_dir
+      @definitions_dir
+    end
+
+    def get_attrs(name, &block)
+      ::ApiSketch::DSL::AttributeParser.new(:root, &block).to_h.merge(name: name)
+    end
+
+    def get_complex_attribute(attribute_name, &block)
+      case attribute_name
+      when :headers
+        ::ApiSketch::DSL::Headers.new(&block).to_a
+      when :parameters
+        params = ::ApiSketch::DSL::Parameters.new(&block).to_h
+        ::ApiSketch::Model::Parameters.new(params)
+      when :responses
+        ::ApiSketch::DSL::Responses.new(&block).to_a
+      end
+    end
+
+end

data/lib/api_sketch/error.rb

@@ -0,0 +1,2 @@
+class ApiSketch::Error < StandardError
+end

data/lib/api_sketch/examples_server.rb

@@ -0,0 +1,54 @@
+class ApiSketch::ExamplesServer
+  def self.call(env)
+    new(env).response.finish
+  end
+
+  def initialize(env)
+    @request = Rack::Request.new(env)
+  end
+
+  def response
+    if api_resource
+      api_response = if api_response_context
+        api_resource.responses.find { |rsp| rsp.name == api_response_context }
+      else
+        api_resource.responses.first
+      end
+
+      if api_response
+        Rack::Response.new do |response|
+          api_response.headers.each do |header|
+            response[header.name] = header.value
+          end
+
+          response['Content-Type'] = 'application/json'
+
+          response.status = Rack::Utils.status_code(api_response.http_status)
+          response.write(ApiSketch::ResponseRenderer.new(api_response.parameters.body, api_response.parameters.body_container_type).to_json)
+        end
+      else
+        api_sketch_message("No any responses defined for this resource", 404)
+      end
+    else
+      api_sketch_message("Resource is not Found", 404)
+    end
+  end
+
+  private
+    def api_resource
+      @api_resource = if @request.params["api_sketch_resource_id"]
+        ApiSketch::Model::Resource.find(@request.params["api_sketch_resource_id"])
+      else
+        ApiSketch::Model::Resource.all.find { |res| res.http_method == @request.request_method && res.path }
+      end
+    end
+
+    def api_response_context
+      @request.params["api_sketch_response_context"]
+    end
+
+    def api_sketch_message(message, status)
+      Rack::Response.new({"api_sketch" => message}.to_json, 404)
+    end
+
+end

data/lib/api_sketch/generators.rb

@@ -0,0 +1,87 @@
+module ApiSketch::Generators
+
+	class Base
+
+	  attr_accessor :definitions_dir, :documentation_dir
+
+	  attr_reader :templates_folder
+
+	  # TODO: Add here some validations for folders existance, etc
+	  def initialize(options = {})
+	    self.definitions_dir = options[:definitions_dir]
+	    self.documentation_dir = options[:documentation_dir]
+	    @templates_folder = File.expand_path("templates/#{self.class.name.split("::").last.downcase}", File.dirname(__FILE__))
+	  end
+
+	  def generate!
+      puts_info("Load definitions")
+	    load_definitions
+      puts_info("Create documentation directory")
+      puts_info("\t path: #{self.documentation_dir}")
+	    create_documentation_directory
+      puts_info("Create documentation files")
+	    create_documentation_files
+	  end
+
+	  private
+	    def create_documentation_directory
+        FileUtils.rm_r(self.documentation_dir, :force => true)
+	      FileUtils.mkdir_p(self.documentation_dir)
+	    end
+
+	    # TODO: This is unfinished sample file generator it should be more complex at some other generators
+	    #       Other generors should inherit from this class and implement this method
+	    def create_documentation_files
+	      raise "This method should be implemented at child class who inherits from ApiSketch::Generators::Base"
+	    end
+
+	    def load_definitions
+        ApiSketch::Model::Resource.reload!(self.definitions_dir)
+	    end
+
+	end
+
+
+	class Bootstrap < ApiSketch::Generators::Base
+
+    def initialize(options = {})
+      super(options)
+      @resource_template = ERB.new(File.read("#{self.templates_folder}/resource.html.erb"))
+    end
+
+    # This is defined here because it is related for this type of generator only
+    def filename_for(resource)
+      resource.id + '.html'
+    end
+
+    private
+      def copy_assets
+        # copy assets from template directory
+        source = File.join(self.templates_folder, 'assets')
+        target = File.join(self.documentation_dir, 'assets')
+        FileUtils.copy_entry(source, target)
+      end
+
+      def create_documentation_files
+        @generator = self
+        copy_assets
+        @resources = ApiSketch::Model::Resource.all
+        @resources.each do |resource|
+          @resource = resource
+
+          filename = File.join(self.documentation_dir, filename_for(@resource))
+          html_data = @resource_template.result(binding)
+
+          dir = File.dirname(filename)
+          unless File.directory?(dir)
+            puts_info("\t create directory: #{dir}")
+            FileUtils.mkdir_p(dir)
+          end
+
+          puts_info("\t write: #{filename}")
+          File.open(filename, 'w+') { |file| file.write(html_data) }
+        end
+      end
+  end
+
+end

data/lib/api_sketch/helpers.rb

@@ -0,0 +1,21 @@
+# Output info message to console.
+#
+# @param message [String] message to output
+def puts_info(message)
+  $stdout.puts "\e[32m[INFO] #{message}\e[0m" if ApiSketch::Config[:debug]
+end
+
+# Output warning message to console.
+#
+# @param message [String] message to output
+def puts_warning(message)
+  $stdout.puts "\e[33m[WARNING] #{message}\e[0m" if ApiSketch::Config[:debug]
+end
+
+# Output error message to console.
+#
+# @param message [String] message to output
+def puts_error(message)
+  $stderr.puts "\e[31m[ERROR] #{message}\e[0m" if ApiSketch::Config[:debug]
+  exit(1)
+end

data/lib/api_sketch/model.rb

@@ -0,0 +1,227 @@
+module ApiSketch::Model
+
+  class Base
+
+    attr_accessor :name, :description
+
+    def initialize(attributes = {})
+      attributes = default_values_hash.merge(attributes)
+      attributes.each do |attribute, value|
+        self.send("#{attribute}=", value)
+      end
+    end
+
+    private
+      def default_values_hash
+        {}
+      end
+
+  end
+
+
+  class Attribute < ApiSketch::Model::Base
+    attr_accessor :data_type, :value, :example, :required, :default, :content
+
+    def example_value(defaults_allowed=false)
+      value = self.example
+      value ||= example_value_default if defaults_allowed
+
+      value.respond_to?(:call) ? value.call : value
+    end
+
+    # TODO: These default values should be configurable via DSL
+    #       Some logic to defer value example from key name, - email from key with email part inside, etc.
+    def example_value_default
+      {
+        integer:   lambda { rand(1000) + 1 },
+        string:    lambda { "random_string_#{('A'..'Z').to_a.shuffle.first(8).join}" },
+        float:     lambda { rand(100) + rand(100) * 0.01 },
+        boolean:   lambda { [true, false].sample },
+        datetime:  lambda { Time.now.strftime("%d-%m-%Y %H:%M:%S") },
+        timestamp: lambda { Time.now.to_i }
+      }[data_type]
+    end
+
+    def to_hash
+      {
+        data_type: self.data_type,
+        example_value: self.example_value,
+        required: !!self.required,
+        default: self.default,
+        content: self.content_to_hash
+      }
+    end
+
+    def content_to_hash
+      if self.content
+        self.content.map do |item|
+          item.to_hash
+        end
+      end
+    end
+
+  end
+
+
+  class Header < ApiSketch::Model::Base
+    attr_accessor :value, :example, :required
+
+    def example_value
+      self.example.respond_to?(:call) ? self.example.call : self.example
+    end
+  end
+
+
+  class Parameters < ApiSketch::Model::Base
+    attr_accessor :query, :body, :query_container_type, :body_container_type
+
+    def initialize(attributes = {})
+      super(attributes)
+      self.query ||= []
+      self.body ||= []
+    end
+
+    def as_full_names
+      fullname_params = self.class.new
+      [:query, :body].each do |param_location|
+        new_params = []
+        self.send(param_location).each do |param|
+          if param.data_type == :document
+            full_names_for(param, param.name, new_params)
+          else
+            new_params << param
+          end
+        end
+        fullname_params.send("#{param_location}=", new_params)
+      end
+      fullname_params
+    end
+
+    private
+      def full_names_for(param, name = "", new_params)
+        name = name.to_s # ensure that this value is always a string
+        if param.content.kind_of?(Array)
+          param.content.each do |attribute|
+            renamed_attribute = attribute.clone
+            renamed_attribute.name = name.empty? ? attribute.name.to_s : "#{name}[#{attribute.name}]"
+            if renamed_attribute.data_type == :document
+              full_names_for(renamed_attribute, renamed_attribute.name, new_params)
+            else
+              new_params << renamed_attribute
+            end
+          end
+        end
+      end
+  end
+
+
+  class Resource < ApiSketch::Model::Base
+
+    attr_accessor :namespace, :action, :path, :http_method, :format, :headers, :parameters, :responses
+
+    # TODO: update this method to provide better id that is used as part of filename
+    def id
+      [self.namespace, self.action].reject { |v| v.nil? || v == "" }.join("/")
+    end
+
+    class << self
+
+      def create(attributes)
+        res = self.new(attributes)
+        res.send(:run_validations!)
+        self.add(res)
+        res
+      end
+
+      def add(resource)
+        @resources ||= []
+        @resources << resource
+      end
+
+      def reset!
+        @resources = []
+      end
+
+      def reload!(definitions_dir)
+        self.reset!
+        ApiSketch::DSL.new(definitions_dir).init!
+      end
+
+      def all
+        @resources ||= []
+      end
+
+      def find(id)
+        self.all.find { |res| res.id == id }
+      end
+
+      def first
+        self.all.first
+      end
+
+      def last
+        self.all.last
+      end
+
+      def count
+        self.all.count
+      end
+
+    end
+
+    private
+      def default_values_hash
+        {
+          http_method: "GET",
+          format: "json",
+          headers: [],
+          parameters: ::ApiSketch::Model::Parameters.new,
+          responses: []
+        }
+      end
+
+      def run_validations!
+        unless self.action =~ /\A\w*\z/
+          message = "'#{self.action}' is invalid action value"
+          # puts_error(message)
+          raise ::ApiSketch::Error, message
+        end
+
+        if self.class.find(self.id)
+          message =  "'#{self.id}' is not unique id. Change values of 'namespace' and/or 'action' attributes"
+          # puts_error(message)
+          raise ::ApiSketch::Error, message
+        end
+      end
+
+  end
+
+
+  class Response < ApiSketch::Model::Base
+    attr_accessor :http_status, :parameters, :format, :headers
+
+    private
+      def default_values_hash
+        {
+          format: "json",
+          headers: [],
+          parameters: ::ApiSketch::Model::Parameters.new
+        }
+      end
+  end
+
+  module SharedBlock
+    @list_hash = {}
+
+    class << self
+      def add(name, block)
+        @list_hash[name] = block
+      end
+
+      def find(name)
+        @list_hash[name] || raise(::ApiSketch::Error, "Shared block '#{name}' is not defined")
+      end
+    end
+  end
+
+end

data/lib/api_sketch/renderers.rb

@@ -0,0 +1,48 @@
+class ApiSketch::ResponseRenderer
+
+  attr_reader :params, :container_type
+
+  def initialize(params, container_type)
+    @params = params
+    @container_type = container_type
+  end
+
+  def to_h
+    render_content(params, container_type)
+  end
+
+  def to_json
+    self.to_h.to_json
+  end
+
+  # TODO: Add this feature in future
+  # def to_xml
+  #   XML conversion code here
+  # end
+
+  private
+    def render_content(items, placeholder_type)
+      placeholder = case placeholder_type
+      when :array then []
+      when :document then {}
+      end
+
+      items.each do |param, index|
+        value =  if [:array, :document].include?(param.data_type) && param.content
+          render_content(param.content, param.data_type)
+        else
+          param.example_value(true)
+        end
+
+        case placeholder_type
+        when :array
+          placeholder << value
+        when :document
+          placeholder[param.name] = value
+        end
+      end
+
+      placeholder
+    end
+
+end