api_sketch 0.1.1 → 0.1.2

data/examples/api_project/resources/users.rb

@@ -0,0 +1,341 @@
+resource "Update user profile" do
+  action "update"
+  description "Authenticated user could update his profile fields and password"
+  path "/api/users/me.json"
+  http_method "PUT"
+  format "json"
+
+  headers do
+    add "Authorization" do
+      value "Token token=:token_value"
+      description ":token_value - is an authorization token value"
+      example { (:A..:z).to_a.shuffle[0,16].join }
+      required true
+    end
+
+    add "X-Test" do
+      value "Test=:perform_test"
+      description ":perform_test - test boolean value"
+      example true
+    end
+  end
+
+  parameters do
+    query :document do
+      string "hello_message" do
+        description "some message"
+      end
+
+      integer "repeat_times" do
+        description "times to repeat hello message"
+      end
+
+      integer "page" do
+        description "page number"
+        required false
+        default 1
+      end
+
+      integer "per_page" do
+        description "items per page amount"
+        required false
+        default 25
+      end
+
+      string "name" do
+        description "place name"
+        required true
+      end
+
+      float "range" do
+        description "search range in km"
+        required false
+        example { rand(100) + rand.round(2) }
+      end
+
+      datetime "start_at" do
+        description "start at datetime"
+        required false
+        example { Time.now.to_s }
+      end
+
+      timestamp "seconds" do
+        description "seconds today"
+        example { Time.now.to_i }
+      end
+
+      array "place_ids" do
+        description "user's places ids"
+        required false
+        content do
+          integer do
+            description "hello number"
+          end
+          string do
+            description "more text here"
+          end
+          document do
+            content do
+              boolean "is_it_true" do
+              end
+            end
+          end
+          document do
+            description "some useless data :)"
+            content do
+              string "test" do
+                description "test string"
+              end
+              document "keys" do
+                content do
+                  integer "sum" do
+                  end
+                  string "details text" do
+                  end
+                end
+              end
+
+            end
+          end
+        end
+      end
+    end
+
+    body :document do
+      document "user" do
+        description "user's parameters fields"
+        required true
+        content do
+          string "email" do
+            description "user's email value"
+          end
+          string "password" do
+            description "user's profile password"
+          end
+          string "first_name" do
+            description "user's first name"
+          end
+          string "last_name" do
+            description "user's last name"
+          end
+          string "country_locode" do
+            example { ["US", "UA"].sample }
+            description "Country location code"
+          end
+
+          document "stats" do
+            content do
+              timestamp "login_at" do
+                description "last login timestamp"
+                example { Time.now.to_i }
+              end
+
+              integer "login_count" do
+                description "login count"
+                example { rand(10000) }
+              end
+
+              string "rank" do
+                description "users rank"
+                example { ["Junior", "Middle", "Senior"].sample }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          document "user" do
+            content do
+              integer "id" do
+                description "User's ID"
+              end
+              string "email" do
+                description "user's email value"
+                example { "user#{rand(100)}@email.com" }
+              end
+              string "first_name" do
+                description "user's first name"
+                example { "First name #{rand(100)}" }
+              end
+              string "last_name" do
+                description "user's last name"
+                example { "Last name #{rand(100)}" }
+              end
+              document "country" do
+                content do
+                  string "name" do
+                    description "Country name"
+                    example { ["USA", "Ukraine", "Poland"].sample }
+                  end
+                  string "id" do
+                    example :location_code
+                    description "Country ID (Location code)"
+                    example { ["US", "UA", "PL"].sample }
+                  end
+                end
+              end
+              array "values" do
+                content do
+                  string do
+                    example { ["A", "B", "C"].sample }
+                  end
+                  integer do
+                    example { rand(100) }
+                  end
+                  document do
+                    content do
+                      string "key" do
+                        example { "Test #{rand(100)}" }
+                      end
+                      timestamp "time" do
+                        example { Time.now.to_i }
+                      end
+                    end
+                  end
+                end
+              end
+              array "authentications" do
+                content do
+                  document do
+                    content do
+                      string "uid" do
+                        description "user's id at social network"
+                        example { 5.times.map { 4.times.map { rand(10).to_s }.join }.join("-") }
+                      end
+                      string "provider" do
+                        example { ["facebook", "twitter", "google_plus"].sample }
+                        description "user's social network type"
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    context "Failure" do
+      http_status :bad_request # 400
+
+      parameters do
+        body :document do
+          document "error" do
+            content do
+              string "message" do
+                description "Error description"
+                example { "Epic fail at your parameters" }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+resource "Get user profile" do
+  action "show"
+  description "Authenticated user could get data from his profile"
+  path "/api/users/me.json"
+  http_method "GET"
+  format "json"
+
+  headers do
+    add "Authorization" do
+      value "Token token=:token_value"
+      description ":token_value - is an authorization token value"
+      example { (:A..:z).to_a.shuffle[0,16].join }
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          document "user" do
+            content do
+              integer "id" do
+                description "User's ID"
+              end
+              string "email" do
+                description "user's email value"
+                example { "user#{rand(100)}@email.com" }
+              end
+              string "first_name" do
+                description "user's first name"
+                example { "First name #{rand(100)}" }
+              end
+              string "last_name" do
+                description "user's last name"
+                example { "Last name #{rand(100)}" }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+end
+
+resource "Create user profile" do
+  action "create"
+  description "User could register his profile"
+  path "/api/users.json"
+  http_method "POST"
+  format "json"
+
+  parameters do
+    body :document do
+      document "user" do
+        description "user's parameters fields"
+        required true
+        content do
+          string "email" do
+            description "user's email value"
+          end
+          string "password" do
+            description "user's profile password"
+          end
+          string "first_name" do
+            description "user's first name"
+          end
+          string "last_name" do
+            description "user's last name"
+          end
+        end
+      end
+    end
+  end
+
+  responses do
+    context "Success" do
+      http_status :ok # 200
+
+      parameters do
+        body :document do
+          string :token do
+            description "Auth token"
+          end
+
+          string :email do
+            description "User email"
+          end
+        end
+      end
+    end
+  end
+
+end

data/lib/api_sketch/config.rb

@@ -4,4 +4,4 @@ require 'mixlib/config'
 # See https://github.com/opscode/mixlib-config
 class ::ApiSketch::Config
   extend Mixlib::Config
-end
+end

data/lib/api_sketch/dsl/attribute_parser.rb

@@ -0,0 +1,19 @@
+class ApiSketch::DSL::AttributeParser < ApiSketch::DSL::Base
+
+  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

data/lib/api_sketch/dsl/attributes.rb

@@ -0,0 +1,45 @@
+class ApiSketch::DSL::Attributes < ApiSketch::DSL::Base
+
+  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
+
+  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

data/lib/api_sketch/dsl/base.rb

@@ -0,0 +1,8 @@
+# All DSL clases should inherit this Base class
+class ApiSketch::DSL::Base
+
+  def use_shared_block(name)
+    self.instance_eval(&::ApiSketch::Model::SharedBlock.find(name))
+  end
+
+end

data/lib/api_sketch/dsl/complex_attribute_parser.rb

@@ -0,0 +1,11 @@
+class ApiSketch::DSL::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

data/lib/api_sketch/dsl/headers.rb

@@ -0,0 +1,17 @@
+class ApiSketch::DSL::Headers < ApiSketch::DSL::Base
+
+  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

data/lib/api_sketch/dsl/parameters.rb

@@ -0,0 +1,31 @@
+class ApiSketch::DSL::Parameters < ApiSketch::DSL::Base
+
+  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

data/lib/api_sketch/dsl/responses.rb

@@ -0,0 +1,22 @@
+class ApiSketch::DSL::Responses < ApiSketch::DSL::Base
+
+  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