api_sketch 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6908ab17b9fdfd6d03c2a70024e302fc9e5b7860
-  data.tar.gz: 4444f8b4898282b779172e6111b59bbf80e586e0
+  metadata.gz: 2c2b16335a821956300f19937d9c5b64d4b2685d
+  data.tar.gz: 152e15df7c7030de612807127bc4ff3d3dcfa654
 SHA512:
-  metadata.gz: bf925a6d9b5431b0a5e9d6f63259c42227e366100a9bc51251e874e0d1424feb6caa2801a5a23640aa221cda181931590361e2355b2df5737214d182b51722a9
-  data.tar.gz: 6b8e5af2fd9decc7b1e1b7c75345f06cb185545dcc9075105ee4c223496a937cb297327feb9278b1c497541d8c8d84861ad39577e97052d2cf269a56d24f12b2
+  metadata.gz: c2a10207ada23e6e82545cf29fa8483b179b29b12960ccf1baf41c5a358476fc2a2e185769ddfb48313aaf19fc624f11138d233cd8b146794ecda998e1b776ae
+  data.tar.gz: 4fa27b22d8c7dbf51ef822378bbba4fc5ed868cb5e3474c341c4a74797e7a64caf120b75951dab3305fdc36714f3bf9c22579833a9a6c1094e0480b30f6c7881

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 0.1.0 / 2015-05-03
+
+- Bootstrap template: put all generated pages data into `{output_folder}/docs` directory. Left `assets` directory outside since it may clash with generated files/folders names.
+- Add endpoint search by conjuction of request `path` & `http_method` for API examples server (Works like normal api server now).
+- Validate HTTP uniquness of method with path, http method and action unique composition and presence.
+- Add `api_sketch_response_array_elements_count` parameter for responses server. It generates responses with provided array elements counts. If array contains different type values than each type of these elements would be placed to response multiple times.
+
 # 0.1.0 / 2015-04-12
 
 - Add documentation

data/README.md

@@ -1,6 +1,8 @@
 # Api Sketch
-------------
 
+[![Gem Version](https://badge.fury.io/rb/api_sketch.svg)](http://badge.fury.io/rb/api_sketch)
+
+---
 api_sketch gem provides you with DSL to describe and create API documentation.
 
 It consists of three main parts:
@@ -63,31 +65,40 @@ $ api_sketch -s -i definitions
 After this server was started response example may be accessed with this kind url:
 
 ```
-http://localhost:3127/.json?api_sketch_resource_id=users/update&api_sketch_response_context=Success
+http://localhost:3127/.json?api_sketch_resource_id=users/update&api_sketch_response_context=Success&api_sketch_response_array_elements_count=1
 ```
 
 ```json
-{
-   "user":{
-      "id":345,
-      "email":"user44@email.com",
-      "first_name":"First name 20",
-      "last_name":"Last name 96",
-      "country":{
-         "name":"Ukraine",
-         "id":"UA"
-      },
-      "authentications":[
-         {
-            "uid":"6668-5565-3835-6085-8727",
-            "provider":"facebook"
-         }
-      ]
-   }
+{
+   "user":{
+      "id":345,
+      "email":"user44@email.com",
+      "first_name":"First name 20",
+      "last_name":"Last name 96",
+      "country":{
+         "name":"Ukraine",
+         "id":"UA"
+      },
+      "authentications":[
+         {
+            "uid":"6668-5565-3835-6085-8727",
+            "provider":"facebook"
+         }
+      ]
+   }
 }
 ```
 
-`api_sketch_resource_id` and `api_sketch_response_context` parameters are used to determine which response should be returned.
+`api_sketch_resource_id` and `api_sketch_response_context` parameters are used to determine which response should be returned. If `api_sketch_response_context` is omitted than it would take first available response.
+
+`api_sketch_response_array_elements_count` - optional parameter that determines amount of elements in generated response arrays. Default value is 3.
+
+Also server supports finding responses by http request method and path.
+
+```
+curl -H "Accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "api_sketch_response_context" : "Success", "api_sketch_response_array_elements_count" : 3}' http://localhost:3127/api/users/me.json
+{"user":{"id":509,"email":"user63@email.com", ... }}
+```
 
 Definitions
 -----------
@@ -368,17 +379,13 @@ TODO
 - Add API index page similar to [Foursquare API docs](https://developer.foursquare.com/docs/)
 - Improve documentation, add more examples
 - Add more documentation templates. For example PDF, curl, some other html styles, etc. It should be configurable as api_sketch command line option. This might be made as some separate extensions gem. There also could be generators for some specific framework api controllers structure scaffold generators.
-- Put all generated pages data into `{output_folder}/docs` directory. Left `assets` directory outside since it may clash with generated files/folders names.
-- API examples server also should support endpoint search by request `path` & `http_method` like normal api server does.
 - Deal with query body at responses (For example redirects may have query body)
-- Validate HTTP method with path, http method and action unique composition
 - Add other request/response types like plaintext, xml, etc (should be supprted both at generator and server)
 - Add realtime viewable page with log for this api examples server application to let client side developers see what data they have sent and how server received it
 - Add more validations to models.
 - Add more specs and tests.
 - Add `shared_block "shared block name"` (definition keyword) search keyword by it's to blocks. Maybe `uses_shared_block "shared block name"`. Maybe shared blocks should be placed into special directory at definitions to be loaded before all examples
 - Add more complex example values autogeneration for API examples server. Derive values from key names. For example string "email" should have some email value as response example.
-- Add `api_sketch_response_array_elements_count` for responses server. It should generate responses with provided array elements counts. If array contains different type values than each type of these elements should be placed to response multiple times.
 - rDoc documentation for code.
 
 Contributing

data/lib/api_sketch/examples_server.rb

@@ -24,10 +24,11 @@ class ApiSketch::ExamplesServer
           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)
+
+          response.write(ApiSketch::ResponseRenderer.new(api_response.parameters.body, api_response.parameters.body_container_type, get_elements_count).to_json)
         end
       else
-        api_sketch_message("No any responses defined for this resource", 404)
+        api_sketch_message("No any responses defined for this resource and context", 404)
       end
     else
       api_sketch_message("Resource is not Found", 404)
@@ -39,7 +40,7 @@ class ApiSketch::ExamplesServer
       @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 }
+        ApiSketch::Model::Resource.find_by_http_method_and_path(@request.request_method, @request.path)
       end
     end
 
@@ -51,4 +52,7 @@ class ApiSketch::ExamplesServer
       Rack::Response.new({"api_sketch" => message}.to_json, 404)
     end
 
-end
+    def get_elements_count
+      @request.params["api_sketch_response_array_elements_count"].to_i
+    end
+end

data/lib/api_sketch/generators.rb

@@ -1,48 +1,52 @@
 module ApiSketch::Generators
 
-	class Base
+  class Base
 
-	  attr_accessor :definitions_dir, :documentation_dir
+    attr_accessor :definitions_dir, :documentation_dir
 
-	  attr_reader :templates_folder
+    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
+    # 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!
+    def generate!
       puts_info("Load definitions")
-	    load_definitions
+      load_definitions
       puts_info("Create documentation directory")
       puts_info("\t path: #{self.documentation_dir}")
-	    create_documentation_directory
+      create_documentation_directory
       puts_info("Create documentation files")
-	    create_documentation_files
-	  end
+      create_documentation_files
+    end
 
-	  private
-	    def create_documentation_directory
+    private
+      def create_documentation_directory
         FileUtils.rm_r(self.documentation_dir, :force => true)
-	      FileUtils.mkdir_p(self.documentation_dir)
-	    end
+        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
+      # 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
+      def load_definitions
         ApiSketch::Model::Resource.reload!(self.definitions_dir)
-	    end
+      end
+
+  end
 
-	end
 
+  class Bootstrap < ApiSketch::Generators::Base
 
-	class Bootstrap < ApiSketch::Generators::Base
+    # Generated folders structure is
+    # 	docs - html folders and files
+    # 	assets - js, css and images. Html styling
 
     def initialize(options = {})
       super(options)
@@ -62,6 +66,12 @@ module ApiSketch::Generators
         FileUtils.copy_entry(source, target)
       end
 
+      def docs_folder
+        # Left assets directory outside since it may clash with generated files/folders names.
+        # Put generated html pages to 'docs' folder
+        "#{self.documentation_dir}/docs"
+      end
+
       def create_documentation_files
         @generator = self
         copy_assets
@@ -69,7 +79,7 @@ module ApiSketch::Generators
         @resources.each do |resource|
           @resource = resource
 
-          filename = File.join(self.documentation_dir, filename_for(@resource))
+          filename = File.join(docs_folder, filename_for(@resource))
           html_data = @resource_template.result(binding)
 
           dir = File.dirname(filename)
@@ -84,4 +94,4 @@ module ApiSketch::Generators
       end
   end
 
-end
+end

data/lib/api_sketch/model.rb

@@ -155,6 +155,10 @@ module ApiSketch::Model
         self.all.find { |res| res.id == id }
       end
 
+      def find_by_http_method_and_path(http_method, path)
+        self.all.find { |res| res.http_method == http_method && res.path == path }
+      end
+
       def first
         self.all.first
       end
@@ -180,17 +184,30 @@ module ApiSketch::Model
         }
       end
 
+      def error_message(message)
+        # puts_error(message)
+        raise ::ApiSketch::Error, message
+      end
+
       def run_validations!
         unless self.action =~ /\A\w*\z/
-          message = "'#{self.action}' is invalid action value"
-          # puts_error(message)
-          raise ::ApiSketch::Error, message
+          error_message("'#{self.action}' is invalid action value")
         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
+          error_message("'#{self.id}' is not unique id. Change values of 'namespace' and/or 'action' attributes")
+        end
+
+        if self.http_method.nil? || self.http_method.empty?
+          error_message("request http_method can't be blank")
+        end
+
+        if self.path.nil? || self.path.empty?
+          error_message("request path can't be blank")
+        end
+
+        if self.class.find_by_http_method_and_path(self.http_method, self.path)
+          error_message("Route '#{self.http_method} #{self.path}' should be unique")
         end
       end
 
@@ -224,4 +241,4 @@ module ApiSketch::Model
     end
   end
 
-end
+end

data/lib/api_sketch/renderers.rb

@@ -1,10 +1,11 @@
 class ApiSketch::ResponseRenderer
 
-  attr_reader :params, :container_type
+  attr_reader :params, :container_type, :elements_count
 
-  def initialize(params, container_type)
-    @params = params
+  def initialize(params, container_type, elements_count)
+    @params = params || {}
     @container_type = container_type
+    @elements_count = elements_count > 0 ? elements_count : 3
   end
 
   def to_h
@@ -28,7 +29,10 @@ class ApiSketch::ResponseRenderer
       end
 
       items.each do |param, index|
-        value =  if [:array, :document].include?(param.data_type) && param.content
+        value = if param.data_type == :array && param.content
+          # Some crazy tricks to get 'elements_count' random elements
+          elements_count.times.inject([]) { |a, _| a += render_content(param.content, param.data_type) }
+        elsif param.data_type == :document && param.content
           render_content(param.content, param.data_type)
         else
           param.example_value(true)
@@ -36,7 +40,11 @@ class ApiSketch::ResponseRenderer
 
         case placeholder_type
         when :array
-          placeholder << value
+          if param.data_type == :array && param.content
+            placeholder += value
+          else
+            placeholder << value
+          end
         when :document
           placeholder[param.name] = value
         end

data/lib/api_sketch/runner.rb

@@ -67,7 +67,6 @@ class ApiSketch::Runner
     if config[:generate] || config[:examples_server]
       raise ApiSketch::Error, "Definitions parameter should be a directory" unless File.directory?(config[:definitions_dir])
       config[:project_name] = File.basename(config[:definitions_dir]).gsub("_", " ").gsub(/\w+/, &:capitalize) if (config[:project_name].nil? || config[:project_name].empty?)
-      puts config[:project_name]
     end
 
     ::ApiSketch::Config.merge!(config)
@@ -89,4 +88,4 @@ class ApiSketch::Runner
     end
   end
 
-end
+end

data/lib/api_sketch/templates/bootstrap/resource.html.erb

@@ -45,7 +45,7 @@
 
 <%
   # Relative reference urls nesting
-  nesting_path_prefix = "./" + "../" * File.dirname(@generator.filename_for(resource)).split("/").count
+  nesting_path_prefix = "./../" + "../" * File.dirname(@generator.filename_for(resource)).split("/").count
 %>
 
 <!DOCTYPE html>
@@ -58,7 +58,7 @@
     <meta name="author" content="">
     <link rel="icon" href="<%= nesting_path_prefix %>assets/images/favicon.ico">
 
-    <title>Project name here</title>
+    <title><%= ApiSketch::Config[:project_name] %> API documentation</title>
 
     <!-- Bootstrap core CSS -->
     <link href="<%= nesting_path_prefix %>assets/stylesheets/bootstrap.min.css" rel="stylesheet">
@@ -95,7 +95,7 @@
         <div class="col-sm-3 col-md-2 sidebar">
           <ul class="nav nav-sidebar">
             <% @resources.each do |resource| %>
-              <li class="<%= 'active' if resource.id == @resource.id %>"><a href="<%= nesting_path_prefix %><%= @generator.filename_for(resource) %>"><%= resource.name %></a></li>
+              <li class="<%= 'active' if resource.id == @resource.id %>"><a href="<%= nesting_path_prefix %>docs/<%= @generator.filename_for(resource) %>"><%= resource.name %></a></li>
             <% end %>
           </ul>
         </div>

data/lib/api_sketch/version.rb

@@ -1,3 +1,3 @@
 module ApiSketch
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/spec/lib/{dsl_spec.rb → api_sketch/dsl_spec.rb}

@@ -2,7 +2,7 @@ require "spec_helper"
 
 describe ApiSketch::DSL do
   context "document" do
-  	context "when all data has key names" do
+    context "when all data has key names" do
       before do
         @block = lambda do
           document do
@@ -14,7 +14,7 @@ describe ApiSketch::DSL do
         end
       end
 
-  		it "should successfully create objects" do
+      it "should successfully create objects" do
         attributes = ApiSketch::DSL::Attributes.new(:array, &@block).to_a
         attribute = attributes.first
         expect(attribute.data_type).to eql :document
@@ -22,7 +22,7 @@ describe ApiSketch::DSL do
         expect(string_key.data_type).to eql :string
         expect(string_key.name).to eql "test_key"
       end
-  	end
+    end
 
     context "when data doesn't have key name" do
       before do
@@ -90,6 +90,78 @@ describe ApiSketch::DSL do
     end
 
     context "incorrect data" do
+      context "request HTTP method presence validation" do
+        before do
+          @invalid_block = Proc.new do
+            resource "API endpoint name" do
+              action "show"
+              namespace "endpoints"
+              path "/api/endpoint/link.json"
+              http_method ""
+            end
+          end
+        end
+
+        it "should return error" do
+          expect { ApiSketch::DSL.new.instance_eval(&@invalid_block) }.to raise_error(::ApiSketch::Error, "request http_method can't be blank")
+        end
+      end
+
+      context "request path method presence validation" do
+        before do
+          @invalid_block = Proc.new do
+            resource "API endpoint name" do
+              action "show"
+              namespace "endpoints"
+              http_method "GET"
+            end
+          end
+        end
+
+        it "should return error" do
+          expect { ApiSketch::DSL.new.instance_eval(&@invalid_block) }.to raise_error(::ApiSketch::Error, "request path can't be blank")
+        end
+      end
+
+      context "Combination of http_method and path is not unique" do
+        before do
+          @block = Proc.new do
+            resource "API endpoint name" do
+              action "show"
+              namespace "endpoints"
+              path "/api/endpoint/link.json"
+              http_method "GET"
+            end
+          end
+
+          @other_block = Proc.new do
+            resource "Create API endpoint name" do
+              action "create"
+              namespace "endpoints"
+              path "/api/endpoint/link.json"
+              http_method "POST"
+            end
+          end
+
+
+          @invalid_block = Proc.new do
+            resource "API some other endpoint name" do
+              action "other_show"
+              namespace "endpoints"
+              path "/api/endpoint/link.json"
+              http_method "GET"
+            end
+          end
+        end
+
+        it "should return error" do
+          ApiSketch::DSL.new.instance_eval(&@block)
+          ApiSketch::DSL.new.instance_eval(&@other_block)
+          expect { ApiSketch::DSL.new.instance_eval(&@invalid_block) }.to raise_error(::ApiSketch::Error, "Route 'GET /api/endpoint/link.json' should be unique")
+        end
+
+      end
+
       context "empty key name at root document" do
         before do
           @block = Proc.new do
@@ -471,4 +543,4 @@ describe ApiSketch::DSL do
 
     end
   end
-end
+end

data/spec/lib/api_sketch/renderers_spec.rb

@@ -0,0 +1,138 @@
+require "spec_helper"
+
+describe ApiSketch::ResponseRenderer do
+
+  before do
+    # Ensure that we have empty resources set for each test
+    ApiSketch::Model::Resource.reset!
+  end
+
+  let(:simple_resource) {
+    Proc.new do
+      resource "Simple data" do
+        action "show"
+        namespace "simple_data"
+        path "/api/test_data.json"
+        http_method "GET"
+        format "json"
+
+        responses do
+          context "Success" do
+            http_status :ok # 200
+
+            parameters do
+              body :document do
+                string "key" do
+                  example { "value" }
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  }
+
+  let(:resource_example_definition) {
+    Proc.new do
+      resource "Get test data" do
+        action "index"
+        namespace "test_endpoints"
+        path "/api/test_data.json"
+        http_method "GET"
+        format "json"
+
+        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"
+                      example { 123 }
+                    end
+                    string "email" do
+                      description "user's email value"
+                      example { "user_test@email.com" }
+                    end
+
+                    array "same_data" do
+                      content do
+                        integer do
+                          example { 42 }
+                        end
+                      end
+                    end
+
+                    array "values" do
+                      content do
+                        string do
+                          example { "Pizza" }
+                        end
+                        integer do
+                          example { 100500 }
+                        end
+                        document do
+                          content do
+                            string "key" do
+                              example { "Text" }
+                            end
+                            timestamp "time" do
+                              example { 1430761823 }
+                            end
+                          end
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  }
+
+  context "instance methods" do
+
+    describe "#to_h" do
+      it "should render data properly" do
+        ApiSketch::DSL.new.instance_eval(&resource_example_definition)
+        response = ApiSketch::Model::Resource.find("test_endpoints/index").responses.find { |rsp| rsp.name == "Success" }
+        result = ApiSketch::ResponseRenderer.new(response.parameters.body, response.parameters.body_container_type, 3).to_h
+
+        expected_hash = {
+          "user" =>
+            {
+              "id" => 123,
+              "email" => "user_test@email.com",
+              "same_data" => [42, 42, 42],
+              "values" =>
+                ["Pizza", 100500, {"key"=>"Text", "time"=>1430761823},
+                  "Pizza", 100500, {"key"=>"Text", "time"=>1430761823},
+                  "Pizza", 100500, {"key"=>"Text", "time"=>1430761823}]
+            }
+        }
+
+        expect(result).to eql expected_hash
+      end
+    end
+
+
+    describe "#to_json" do
+      it "should return proper json" do
+        ApiSketch::DSL.new.instance_eval(&simple_resource)
+        response = ApiSketch::Model::Resource.find("simple_data/show").responses.find { |rsp| rsp.name == "Success" }
+        result = ApiSketch::ResponseRenderer.new(response.parameters.body, response.parameters.body_container_type, 1).to_json
+
+        expected_json = {"key" => "value"}.to_json
+        expect(result).to eql expected_json
+      end
+    end
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api_sketch
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Alexey Suhoviy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-13 00:00:00.000000000 Z
+date: 2015-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mixlib-cli
@@ -156,7 +156,8 @@ files:
 - lib/api_sketch/templates/bootstrap/assets/stylesheets/dashboard.css
 - lib/api_sketch/templates/bootstrap/resource.html.erb
 - lib/api_sketch/version.rb
-- spec/lib/dsl_spec.rb
+- spec/lib/api_sketch/dsl_spec.rb
+- spec/lib/api_sketch/renderers_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/suhovius/api_sketch
 licenses:
@@ -183,5 +184,6 @@ signing_key:
 specification_version: 4
 summary: API Prototyping and API Documentation Tool
 test_files:
-- spec/lib/dsl_spec.rb
+- spec/lib/api_sketch/dsl_spec.rb
+- spec/lib/api_sketch/renderers_spec.rb
 - spec/spec_helper.rb