kanpachi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6e70d69f07c62ef21800d0be7c54619c19e3fdad
+  data.tar.gz: ff42d674ead45d9b803056b26f9abcacc412fc05
+SHA512:
+  metadata.gz: 7de088c8bd7856c838b41d9c5918b3a153152779500f3bbb94c4d94ad667e7bf322ca5fe391e763696a80d46d7e18196a78ebbc3d7b609384308e18b04a29629
+  data.tar.gz: 01289cc3cdc94e99c2a2fc1c082420c78ba031ec0413634f5c25744120450bcbdac5f3b2d7146cd0351d65ba1209c0408c90783f43f02b29b8fb42df9755ec7d

data/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby
+  - rbx-19mode
+  - ruby-head
+  - jruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Kanpachi Changelog
+
+## 0.0.1
+
+* First version.

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kanpachi.gemspec
+gemspec
+
+gem 'coercible', git: 'https://github.com/solnic/coercible.git'

data/Guardfile

@@ -0,0 +1,14 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb})
+  watch(%r{^lib/kanpachi/(.*/)?([^/]+)\.rb})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb})      { 'test' }
+
+  # with Minitest::Spec
+  watch(%r{^spec/(.*)_spec\.rb})
+  watch(%r{^lib/kanpachi/(.+)\.rb})         { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/spec_helper\.rb}) { 'spec' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jack Chu
+
+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,131 @@
+# Kanpachi
+
+[![CI Build Status](https://secure.travis-ci.org/kamui/kanpachi.png?branch=master)](http://travis-ci.org/kamui/kanpachi)
+
+Kanpachi is a ruby gem that provides a DSL to describe your web API, generate documentation, and will even eventually
+help you implement it.
+
+Resource input parameters are defiend with the [mutations](https://github.com/cypriss/mutations) gem. You can refer to
+their [wiki](https://github.com/cypriss/mutations/wiki/Filtering-Input) to find out how to use their DSL.
+
+Response representations are defined as [Roar](https://github.com/apotonick/roar) representers. You can check out the
+[representable docs](https://github.com/apotonick/representable) to figure out how to customize your responses.
+
+To check out an example API project, checkout [kanpachi-example](https://github.com/kamui/kanpachi-example).
+
+## Example
+
+Below is an example of one of Twitter's API endpoints partially described in Kanpachi.
+
+```ruby
+api 'Twitter' do
+  # API meta data
+  title 'REST API v1.1 Resources'
+  description 'This describes the resources that make up the official Twitter API v1.1'
+  host 'api.twitter.com'
+
+  # Define global error responses
+  error :malformed_params do
+    description 'Sending invalid JSON will result in a 400 Bad Request response.'
+
+    response do
+      status 400
+      header 'Content-Type', 'application/json'
+      representation do
+        property :message, type: String
+      end
+    end
+  end
+
+  section 'Timelines' do
+    description 'Timelines are collections of Tweets, ordered with the most recent first.'
+
+    resource :get, '/statuses/mentions_timeline' do
+      name 'Mentions timeline'
+      description <<-TEXT
+Returns the 20 most recent mentions (tweets containing a users's @screen_name) for the authenticating user.
+
+The timeline returned is the equivalent of the one seen when you view [your mentions](https://twitter.com/mentions) on twitter.com.
+
+This method can only return up to 800 tweets.
+
+See [__Working with Timelines__](https://dev.twitter.com/docs/working-with-timelines) for instructions on traversing timelines.
+TEXT
+      versions '1.1', 1.0
+      ssl true
+      formats :json
+
+      # Params are a subclass of Mutations::Command
+      params do
+        required do
+        end
+
+        optional do
+          integer :count, doc: 'Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if `include_rts` is not supplied. It is recommended you always send `include_rts=1` when using this API method.'
+          integer :since_id, doc: 'Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.', example: 12345
+          integer :max_id, doc: 'Returns results with an ID less than (that is, older than) or equal to the specified ID.', example: 54321
+          boolean :trim_user, doc: 'When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.', example: true
+          boolean :contributor_details, doc: 'This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.', example: true
+          boolean :include_entities, doc: 'The `entities` node will be disincluded when set to false.', example: false
+        end
+      end
+
+      # Multiple responses are supported
+      response :default do
+        status 200
+        header 'Content-Type', 'application/json'
+
+        # Response representations include Roar::Representer
+        representation do
+          include ::Representable::JSON::Collection
+          property :title, type: String, doc: "it's the title", example: 'The Title'
+          collection :coordinates, doc: "it's the coordinates", example: [100.4, 45.1]
+        end
+      end
+    end
+  end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kanpachi'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kanpachi
+
+## Usage
+
+Create a new API
+
+```bash
+$ kanpachi new my_api
+$ cd my_api
+```
+
+Build HTML documentation
+
+```bash
+$ kanpachi build
+```
+
+Start a documentation server
+
+```bash
+$ kanpachi server
+```
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.test_files = FileList['spec/**/*_spec.rb']
+  t.verbose = true
+end
+
+task default: :test

data/bin/kanpachi

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require_relative '../lib/kanpachi/cli'
+
+# Hack to populate options['reload_paths'] with api path
+if ARGV[0] == 'server'
+  reload_paths = false
+  ARGV.each_with_index do |arg, i|
+    if arg.start_with?('--reload_paths=')
+      ARGV[i] = "#{ARGV[i]},api/[^\.](.*)\.rb$"
+      reload_paths = true
+    end
+  end
+  ARGV << "--reload_paths=api/[^\.](.*)\.rb$" unless reload_paths
+end
+
+Kanpachi::CLI.start(ARGV)

data/examples/twitter.rb

@@ -0,0 +1,122 @@
+require 'roar/representer/json'
+require 'roar/representer/feature/hypermedia'
+
+module UserRepresenter
+  include Roar::Representer::JSON
+  include Roar::Representer::Feature::Hypermedia
+  property :first_name, type: String, required: true, doc: "it's the first name"
+  property :last_name, type: String, required: true, doc: "it's the last name"
+end
+
+api 'Twitter' do
+  title 'REST API v1.1 Resources'
+  description 'This describes the resources that make up the official Twitter API v1.1'
+  host 'api.twitter.com'
+
+  error :malformed_params do
+    description 'Sending invalid JSON will result in a 400 Bad Request response.'
+
+    response do
+      status 400
+      header 'Content-Type', 'application/json'
+      representation do
+        property :message, type: String
+      end
+    end
+  end
+
+  section 'Timelines' do
+    description 'Timelines are collections of Tweets, ordered with the most recent first.'
+
+    resource :get, '/statuses/mentions_timeline' do
+      name 'Mentions timeline'
+      description <<-TEXT
+Returns the 20 most recent mentions (tweets containing a users's @screen_name) for the authenticating user.
+
+The timeline returned is the equivalent of the one seen when you view your mentions on twitter.com.
+
+This method can only return up to 800 tweets.
+
+See __Working with Timelines__ for instructions on traversing timelines.
+TEXT
+      versions '1.1'
+      ssl true
+      formats :json
+
+      params do
+        optional do
+          integer :count, doc: 'Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if `include_rts` is not supplied. It is recommended you always send `include_rts=1` when using this API method.'
+          integer :since_id, doc: 'Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
+
+__Example Values__: 12345'
+          integer :max_id, doc: 'Returns results with an ID less than (that is, older than) or equal to the specified ID.
+
+__Example Values__: 54321'
+          boolean :trim_user, doc: 'When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
+
+__Example Values__: true'
+          boolean :contributor_details, doc: 'This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.
+
+__Example Values__: true'
+          boolean :include_entities, doc: 'The `entities` node will be disincluded when set to false.
+
+__Example Values__: false'
+        end
+      end
+
+      response do
+        status 200
+        header 'Content-Type', 'application/json'
+        representation do
+          property :id, type: Integer, doc: "it's the id"
+          property :title, type: String, doc: "it's the title"
+          collection :users, extend: UserRepresenter, doc: "it's the users"
+        end
+      end
+    end
+
+    resource :get, '/statuses/user_timeline' do
+      name 'User timeline'
+      description <<-TEXT
+Returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters.
+
+User timelines belonging to protected users may only be requested when the authenticated user either "owns" the timeline or is an approved follower of the owner.
+
+The timeline returned is the equivalent of the one seen when you view a user's profile on twitter.com.
+
+This method can only return up to 3,200 of a user's most recent Tweets. Native retweets of other statuses by the user is included in this total, regardless of whether include_rts is set to false when requesting this resource.
+
+See Working with Timelines for instructions on traversing timelines.
+
+See Embeddable Timelines, Embeddable Tweets, and GET statuses/oembed for tools to render Tweets according to Display Requirements.
+TEXT
+      versions '1.1'
+      ssl true
+      formats :json
+
+      params do
+        optional do
+          integer :user_id
+          string :screen_name
+          integer :since_id
+          integer :count
+          integer :max_id
+          boolean :trim_user
+          boolean :exclude_replies
+          boolean :contributor_details
+          boolean :include_rts
+        end
+      end
+
+      response do
+        status 200
+        header 'Content-Type', 'application/json'
+        representation do
+          property :id, type: Integer, doc: "it's the id"
+          property :title, type: String, doc: "it's the title"
+          collection :users, extend: UserRepresenter, doc: "it's the users"
+        end
+      end
+    end
+  end
+end

data/kanpachi.gemspec

@@ -0,0 +1,45 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kanpachi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "kanpachi"
+  spec.version       = Kanpachi::VERSION
+  spec.authors       = ["Jack Chu"]
+  spec.email         = ["kamuigt@gmail.com"]
+  spec.description   = %q{Web API DSL}
+  spec.summary       = %q{DSL for describing Web APIs}
+  spec.homepage      = "https://github.com/kamui/kanpachi"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  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 'thor'
+  spec.add_dependency 'slim'
+  spec.add_dependency 'roar'
+  spec.add_dependency 'representable'
+  spec.add_dependency 'mutations'
+  spec.add_dependency 'virtus', '>= 1.0.0.beta7'
+  spec.add_dependency 'coercible'
+  spec.add_dependency 'kramdown'
+  spec.add_dependency 'inflecto'
+  spec.add_dependency 'middleman', '>= 3.1.5'
+  spec.add_dependency 'slim', '>= 1.3.6'
+
+  # Live-reloading plugin
+  spec.add_dependency 'middleman-livereload', '>= 3.1.0'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'guard', '>= 2.0.0.beta.3'
+  spec.add_development_dependency 'guard-minitest'
+
+  # For faster file watcher updates on Windows:
+  # spec.add_development_dependency 'wdm', '>= 0.1.0'
+  # gem "wdm", "~> 0.1.0", :platforms => [:mswin, :mingw]
+end

data/lib/base_hash.rb

@@ -0,0 +1,41 @@
+module Kanpachi
+  class BaseHash
+    class UnknownKey < StandardError; end
+    class DuplicateKey < StandardError; end
+
+    def initialize
+      @hash = {}
+    end
+
+    # Returns a hash of hash
+    #
+    # @return [Hash<Object>] Internal hash.
+    # @api public
+    def all
+      @hash
+    end
+
+    # Add a resource to the list
+    #
+    # @param [Object] The resource to add.
+    # @return [Hash<Object>] Internal hash.
+    # @raise DuplicateKey If a resource is being duplicated.
+    # @api public
+    def add(key, value)
+      if @hash.key?(attr_key)
+        raise DuplicateKey, 'The key #{attr_key} already exists'
+      end
+      @hash[key] = value
+    end
+
+    # Returns value based on its key
+    #
+    # @param [String, Symbol] key The key of the value you are looking for.
+    # @return [Object] The value returned from the hash.
+    #
+    # @api public
+    def find(key)
+      all[key]
+    end
+  end
+end

data/lib/kanpachi/api.rb

@@ -0,0 +1,22 @@
+require 'kanpachi/error_list'
+require 'kanpachi/section_list'
+require 'kanpachi/resource_list'
+
+module Kanpachi
+  class API
+    attr_reader :name
+    attr_reader :errors
+    attr_reader :sections
+    attr_reader :resources
+    attr_accessor :title
+    attr_accessor :description
+    attr_accessor :host
+
+    def initialize(name)
+      @name = name
+      @errors = ErrorList.new
+      @sections = SectionList.new
+      @resources = ResourceList.new
+    end
+  end
+end

data/lib/kanpachi/api_list.rb

@@ -0,0 +1,61 @@
+module Kanpachi
+  # Module to keep track of all APIs
+  #
+  # @api public
+  module APIList
+    module_function
+
+    @list ||= {}
+
+    # Returns a hash of APIs
+    #
+    # @return [Hash<Kanpachi::API>] All the added APIs.
+    # @api public
+    def to_hash
+      @list
+    end
+
+    # Returns an array of APIs
+    #
+    # @return [Array<Kanpachi::API>] List of added APIs.
+    # @api public
+    def all
+      @list.values
+    end
+
+    # Add a resource to the list
+    #
+    # @param [Kanpachi::API] The API to add.
+    # @return [Hash<Kanpachi::API>] All the added APIs.
+    # @raise DuplicateAPI If a resource is being duplicated.
+    # @api public
+    def add(api)
+      @list[api.name] = api
+    end
+
+    # Delete a resource to the list
+    #
+    # @param [String] The name of the API to delete.
+    # @api public
+    def delete(name)
+      @list.delete(name)
+    end
+
+    # Returns a API based on its name
+    #
+    # @param [String] name The name of the API you are looking for.
+    # @return [Kanpachi::API] The found API.
+    #
+    # @api public
+    def find(name)
+      @list[name]
+    end
+
+    # Clears all APIs
+    #
+    # @api public
+    def clear
+      @list = {}
+    end
+  end
+end

data/lib/kanpachi/cli/doc.rb

@@ -0,0 +1,62 @@
+ENV['MM_ROOT'] = '/Users/jack/Development/kanpachi/lib/kanpachi/doc'
+
+module Kanpachi
+  module SubCommand
+  # class CLI < Thor
+    class Doc < Thor
+      namespace :doc
+
+      desc "doc:generate_doc API_NAME, SOURCE_PATH DESTINATION_PATH", "Generate HTML documentation for Kanpachi web services"
+      def generate_doc(api_name, source_path, destination_path="doc")
+        puts "Starting"
+        api_files = Dir.glob(File.join(destination_root, source_path, "**", "*.rb"))
+        if api_files.empty?
+          puts "No ruby files in source_path: #{File.join(destination_root, source_path)}"
+          return
+        end
+        api_files.each do |file|
+          require file
+        end
+
+        api = APIList.find(api_name)
+
+        require 'fileutils'
+        destination = File.join(destination_root, destination_path)
+        FileUtils.mkdir_p(destination) unless File.exist?(destination)
+        File.open("#{destination}/index.html", "w"){|f| f << doc_template.result(binding)}
+        puts "Documentation available there: #{destination}/index.html"
+        `open #{destination}/index.html` if RUBY_PLATFORM =~ /darwin/ && !ENV['DONT_OPEN']
+      end
+
+      private
+
+      def response_html(attrs)
+        response_template.result(binding)
+      end
+
+      def input_params_html(required, optional)
+        input_params_template.result(binding)
+      end
+
+      def input_params_template
+        file = resources.join '_input_params.erb'
+        ERB.new File.read(file)
+      end
+
+      def response_template
+        file = resources.join '_response.erb'
+        ERB.new File.read(file)
+      end
+
+      def doc_template
+        file = resources.join 'template.erb'
+        ERB.new File.read(file)
+      end
+
+      def resources
+        require 'pathname'
+        @resources ||= Pathname.new(File.join(File.dirname(__FILE__), 'doc_generator'))
+      end
+    end
+  end
+end

data/lib/kanpachi/cli.rb

@@ -0,0 +1,32 @@
+require 'thor'
+require 'inflecto'
+require 'json'
+require 'middleman-core'
+require 'middleman-core/cli'
+require 'middleman-core/profiling'
+require_relative '../kanpachi'
+require_relative 'commands/new'
+
+ENV['MM_ROOT'] = File.join(File.expand_path(File.dirname(__FILE__)), 'documentation')
+
+class Middleman::Cli::Server
+  default_task :server
+end
+
+class Middleman::Cli::Build
+  default_task :build
+end
+
+module Kanpachi
+  class CLI < Thor
+    namespace :kanpachi
+
+    register Commands::New, 'new', 'new [NAME]', 'Generate a new API'
+
+    task = ::Middleman::Cli::Server.tasks['server']
+    register ::Middleman::Cli::Server, 'server', task.usage, task.description, task.options
+
+    task = ::Middleman::Cli::Build.tasks['build']
+    register ::Middleman::Cli::Build, 'build', task.usage, task.description, task.options
+  end
+end

data/lib/kanpachi/commands/new.rb

@@ -0,0 +1,26 @@
+require 'thor/group'
+
+module Kanpachi
+  module Commands
+    class New < Thor::Group
+      include Thor::Actions
+
+      desc 'Generate a new API'
+      argument :name, type: :string, desc: "The name of the API to generate"
+      class_option :test_framework, default: :minitest
+
+      def self.source_root
+        File.expand_path(File.join('..', 'templates'), File.dirname(__FILE__))
+      end
+
+      def create_app
+        directory ".", "#{name}"
+      end
+
+      protected
+      def name_const
+        @name_const ||= Inflecto.camelize(name.gsub(/\W/, '_').squeeze('_'))
+      end
+    end
+  end
+end