api_sketch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6908ab17b9fdfd6d03c2a70024e302fc9e5b7860
+  data.tar.gz: 4444f8b4898282b779172e6111b59bbf80e586e0
+SHA512:
+  metadata.gz: bf925a6d9b5431b0a5e9d6f63259c42227e366100a9bc51251e874e0d1424feb6caa2801a5a23640aa221cda181931590361e2355b2df5737214d182b51722a9
+  data.tar.gz: 6b8e5af2fd9decc7b1e1b7c75345f06cb185545dcc9075105ee4c223496a937cb297327feb9278b1c497541d8c8d84861ad39577e97052d2cf269a56d24f12b2

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.ruby-gemset

@@ -0,0 +1 @@
+api_sketch

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.2

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# 0.1.0 / 2015-04-12
+
+- Add documentation
+- Add API Examples server
+
+# 0.0.1 / 2015-01-24
+
+Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in api_sketch.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Alexey Suhoviy
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,404 @@
+# Api Sketch
+------------
+
+api_sketch gem provides you with DSL to describe and create API documentation.
+
+It consists of three main parts:
+
+1. API definitions DSL
+2. Documentation generator
+3. API example responses server
+
+---
+
+Installation
+------------
+
+Include the gem in your Gemfile:
+
+```ruby
+gem 'api_sketch'
+```
+
+Or install it yourself as:
+
+    $ gem install api_sketch
+
+Usage
+-----
+
+Gem is bundled with the same named executable. It's supported options list is provided below.
+
+```
+$ api_sketch -h
+Usage: /bin/api_sketch (options)
+    -d, --debug                      Run in verbose mode
+    -i, --input DEFINITIONS          Path to the folder with api definitions (required)
+    -o, --output DOCUMENTATION       Path to the folder where generated documentation should be saved (Default is 'documentation' folder in current folder)
+    -s, --server                     Run api examples server
+    -p, --port PORT                  Api examples server port (Default is 3127)
+    -g, --generate                   Generate documentation from provided definitions
+    -n, --name PROJECT_NAME          Name of the project. (Default is derived from DEFINITIONS folder name)
+    -v, --version                    Show version number
+    -h, --help                       Show this help
+```
+
+### Documentation generation
+
+Documentaion generation command example:
+
+```
+$ api_sketch -g -i definitions -o documentation
+```
+### API example responses server
+
+Start API example responses server command example:
+
+```
+$ api_sketch -s -i definitions
+[2015-04-12 20:46:19] INFO  WEBrick 1.3.1
+[2015-04-12 20:46:19] INFO  ruby 2.1.2 (2014-05-08) [x86_64-darwin13.0]
+[2015-04-12 20:46:19] INFO  WEBrick::HTTPServer#start: pid=5874 port=3127
+```
+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
+```
+
+```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"
+         }
+      ]
+   }
+}
+```
+
+`api_sketch_resource_id` and `api_sketch_response_context` parameters are used to determine which response should be returned.
+
+Definitions
+-----------
+
+##### Folder
+
+API definitions files should be placed into directory with structure similar to `definitions` folder in this example. Directory may have only one file or many files and folders with files. Resurce's `namespace` is derived from this hierachical structure.
+
+```
+definitions
+├── places.rb
+├── users
+│   └── points.rb
+└── users.rb
+```
+##### DSL
+
+Definitions DSL is writen in ruby. It consists of special keywords that are used to describe API endpoint resource's request options, url, and list of possible responses.
+
+Here is dummy example of `resource` definition that includes most part of DSL syntax.
+
+`action` and `namespace` both form resource ID that should be unique. For this current case resource ID would be `users/update`.
+
+If `namespace` is omitted than it would be derived from folders structure and file name where this defintion is placed in. So, for example if definition is placed inside `users/points.rb` than it's namespace is `users/points`.
+
+DSL provides `path`, `http_method`, `headers`, `parameters` keywords for request data definition. Parameters could be placed at `query` and `body` containers. Both of them could have `:array` or `:document` structure.
+
+Supported attribute types are: `integer`, `string`, `float`, `boolean`, `datetime`, `timestamp`, `document`, `array`
+
+Each attribute should have name, could have `description`, `example` value, could be `required`.
+
+`example` keyword accepts callable blocks or just some simple values. Callable blocks may give new value each time `example_value` is requested.
+
+Array and query attribute types have `content` keyword where their contents are placed in.
+
+Each `resource` could have many `responses` with different `context`. For example succesful one and few with different errors. Especially for `responses` it is better to provide detailed `example` values as they could be used as responses by examples server.
+
+Resource `parameters` section's syntax it the same as for `resource` request parameters.
+
+```ruby
+resource "Update user profile" do # Resource name
+  action "update"
+  namespace "users"
+  description "Authenticated user could update his profile fields and password"
+  path "/api/users/me.json" # Server path where this endpoint would be processed
+  http_method "PUT" # http request method
+  format "json" # response format
+
+  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
+    # parametes could be query and body
+    query :document do
+      string "hello_message" do
+        description "some message"
+      end
+
+      integer "repeat_times" do
+        description "times to repeat hello message"
+      end
+    end
+
+    query :document do
+      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 "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" }
+                        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
+```
+
+For more detailed DSL features examples check DSL test files at spec folder.
+
+TODO
+----
+
+- Clean genrated documentation html template css, javascripts. Remove useless classes, html, etc.
+- Add local javascript search feature at generated html docs
+- 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
+------------
+
+1. Fork it ( https://github.com/suhovius/api_sketch/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Inspirations
+------------
+- [Calamum](https://github.com/malachheb/calamum)
+- [Apiary](http://apiary.io/blueprint)
+- [IO Docs](https://github.com/mashery/iodocs)
+- [Swagger](https://developers.helloreverb.com/swagger)
+
+
+License
+-------
+
+ApiSketch is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec
+

data/api_sketch.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+require File.expand_path('../lib/api_sketch/version', __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name          = "api_sketch"
+  spec.version       = ApiSketch::VERSION
+  spec.authors       = ["Alexey Suhoviy"]
+  spec.email         = ["martinsilenn@gmail.com"]
+  spec.summary       = %q{API Prototyping and API Documentation Tool}
+  spec.description   = %q{Gem provides DSL for API documentation generation and API request examples server}
+
+  spec.homepage      = "https://github.com/suhovius/api_sketch"
+
+  spec.license       = "MIT"
+  spec.post_install_message = "Thanks for installing!"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'mixlib-cli'
+  spec.add_dependency 'mixlib-config'
+  spec.add_dependency 'rack'
+  spec.add_dependency 'rack-contrib'
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/bin/api_sketch

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'api_sketch'
+rescue LoadError
+  require 'rubygems'
+  require 'api_sketch'
+end
+
+ApiSketch::Runner.new.run

data/lib/api_sketch/config.rb

@@ -0,0 +1,7 @@
+require 'mixlib/config'
+
+# Provides a class-based configuration object.
+# See https://github.com/opscode/mixlib-config
+class ::ApiSketch::Config
+  extend Mixlib::Config
+end