kanpachi 0.0.1

data/lib/kanpachi/resource.rb

@@ -0,0 +1,56 @@
+require 'set'
+require 'kanpachi/resource/params'
+require 'kanpachi/response_list'
+
+module Kanpachi
+  # The Resource class
+  #
+  # @api public
+  class Resource
+    attr_reader :http_verb
+    attr_reader :url
+    attr_reader :formats
+    attr_reader :versions
+    attr_reader :responses
+    attr_accessor :params
+    attr_accessor :name
+    attr_accessor :description
+    attr_accessor :priority
+    attr_accessor :ssl
+    attr_accessor :authentication
+
+    # Resource constructor
+    #
+    # @param http_berb [Symbol] Resource http verb.
+    # @param url [String] Resource's url. The url will automatically be prepended a slash if it doesn't already contain one.
+    # @api public
+    def initialize(http_verb, url)
+      @url                 = url.start_with?('/') ? url : "/#{url}"
+      @http_verb           = http_verb
+      @formats             = Set.new
+      @versions            = Set.new
+      @priority            = 50
+      @ssl                 = false
+      @authentication      = false
+      @params              = Class.new(Params)
+      @responses           = Kanpachi::ResponseList.new
+    end
+
+    # Returns true if the resource has defined any params.
+    #
+    # @return [Boolean]
+    def params?
+      !(params.input_filters.required_inputs.empty? && params.input_filters.optional_inputs.empty?)
+    end
+
+    # Compare two resources using the priority
+    def <=> (other)
+      priority <=> other.priority
+    end
+
+    # Returns the http verb concatenated with the url
+    def route
+      "#{@http_verb.to_s.upcase} #{@url}"
+    end
+  end
+end

data/lib/kanpachi/resource_list.rb

@@ -0,0 +1,71 @@
+module Kanpachi
+  # Class to keep track of all defined resources
+  #
+  # @api public
+  class ResourceList
+    class UnknownResource < StandardError; end
+    class DuplicateResource < StandardError; end
+
+    def initialize
+      @list = {}
+    end
+
+    # Returns a hash of resources
+    #
+    # @return [Hash<Kanpachi::Resource>] All the added resources.
+    # @api public
+    def to_hash
+      @list
+    end
+
+    # Returns an array of resources
+    #
+    # @return [Array<Kanpachi::Resource>] List of added resources.
+    # @api public
+    def all
+      @list.values
+    end
+
+    # Add a resource to the list
+    #
+    # @param [Kanpachi::Resource] The resource to add.
+    # @return [Hash<Kanpachi::Resource>] All the added resources.
+    # @raise DuplicateResource If a resource is being duplicated.
+    # @api public
+    def add(resource)
+      if @list.key? resource.route
+        raise DuplicateResource, "A resource accessible via #{resource.http_verb} #{resource.url} already exists"
+      end
+      @list[resource.route] = resource
+    end
+
+    # Returns a resource based on its name
+    #
+    # @param [String] name The name of the resource you are looking for.
+    # @raise [UnknownResource] if a resource with the passed name isn't found.
+    # @return [Kanpachi::Resource] The found resource.
+    #
+    # @api public
+    def named(name)
+      resource = all.detect { |resource| resource.name == name }
+      if resource.nil?
+        raise UnknownResource, "Resource named #{name} doesn't exist"
+      else
+        resource
+      end
+    end
+
+    # Returns a resource based on its verb and url
+    #
+    # @param [String] verb The request method (GET, POST, PUT, DELETE)
+    # @param [String] url The url of the resource you are looking for.
+    # @return [Nil, Kanpachi::Resource] The found resource.
+    #
+    # @api public
+    def find(verb, url)
+      http_verb = verb.to_s.upcase
+      route = "#{http_verb} #{url}"
+      @list[route]
+    end
+  end
+end

data/lib/kanpachi/response.rb

@@ -0,0 +1,68 @@
+require 'roar/representer'
+require 'roar/representer/feature/hypermedia'
+require 'representable/json/collection'
+require 'representable/json/hash'
+
+module Kanpachi
+  class Response
+    attr_reader :name
+    attr_reader :headers
+    attr_accessor :status
+    attr_accessor :representation
+
+    def initialize(name)
+      @name = name
+      @status = 200
+      @headers = {}
+      @representation = Module.new { include Representation }
+    end
+
+    module Representation
+      def self.included(base)
+        base.class_eval do
+          include Roar::Representer
+          include Roar::Representer::Feature::Hypermedia
+
+          def self.example
+            example = Hash.new
+            self.properties.each do |key, value|
+              if value[:hash]
+                example[key] = value[:extend] ? value[:extend].example : (value[:example] || Hash.new)
+              elsif value[:collection]
+                example[key] = value[:extend] ? [value[:extend].example] : (value[:example] || Array.new)
+              elsif value[:type] == Integer
+                example[key] = value[:example] || 1
+              elsif value[:type] == String
+                example[key] = value[:example] || 'String'
+              elsif !!value[:type] == value[:type]
+                example[key] = value[:example] || true
+              elsif value[:type] == DateTime
+                example[key] = value[:example] || "2013-01-01T19:06:43Z"
+              else
+                example[key] = value[:example] || 'String'
+              end
+            end
+            if self.included_modules.include?(::Representable::JSON::Collection)
+              example = [example]
+            elsif self.included_modules.include?(::Representable::JSON::Hash)
+              example = example['_self'] || Hash.new
+            end
+            example
+          end
+
+          def self.properties
+            hash = Hash.new
+            representable_attrs.each do |definition|
+              if definition.options[:extend]
+                hash[definition.name] = definition.options.merge(definition.options[:extend].properties)
+              else
+                hash[definition.name] = definition.options
+              end
+            end
+            hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kanpachi/response_list.rb

@@ -0,0 +1,51 @@
+module Kanpachi
+  # Class to keep track of all defined responses
+  #
+  # @api public
+  class ResponseList
+    class DuplicateResponse < StandardError; end
+
+    def initialize
+      @list = {}
+    end
+
+    # Returns a hash of responses
+    #
+    # @return [Hash<Kanpachi::Response>] All the added responses.
+    # @api public
+    def to_hash
+      @list
+    end
+
+    # Returns an array of responses
+    #
+    # @return [Array<Kanpachi::Response>] List of added responses.
+    # @api public
+    def all
+      @list.values
+    end
+
+    # Add a response to the list
+    #
+    # @param [Kanpachi::Response] response The response to add.
+    # @return [Hash<Kanpachi::Response>] All the added responses.
+    # @raise DuplicateResponse If a response is being duplicated.
+    # @api public
+    def add(response)
+      if @list.key? response.name
+        raise DuplicateResponse, "A response named #{response.name} already exists"
+      end
+      @list[response.name] = response
+    end
+
+    # Returns a response based on its verb and url
+    #
+    # @param [String] name The name of the response you are looking for.
+    # @return [Nil, Kanpachi::Response] The found response.
+    #
+    # @api public
+    def find(name)
+      @list[name]
+    end
+  end
+end

data/lib/kanpachi/section.rb

@@ -0,0 +1,15 @@
+module Kanpachi
+  # Class for section data.
+  #
+  # @api public
+  class Section
+    attr_reader :name
+    attr_reader :routes
+    attr_accessor :description
+
+    def initialize(name)
+      @name = name
+      @routes = []
+    end
+  end
+end

data/lib/kanpachi/section_list.rb

@@ -0,0 +1,46 @@
+module Kanpachi
+  # Class to keep track of all defined sections
+  #
+  # @api public
+  class SectionList
+    def initialize
+      @list = {}
+    end
+
+    # Returns a hash of sections
+    #
+    # @return [Hash<Kanpachi::Section>] All the added sections.
+    # @api public
+    def to_hash
+      @list
+    end
+
+    # Returns an array of sections
+    #
+    # @return [Array<Kanpachi::Section>] List of added sections.
+    # @api public
+    def all
+      @list.values
+    end
+
+    # Add a section to the list
+    #
+    # @param [Kanpachi::Section] section The section to add.
+    # @return [Hash<Kanpachi::Section>] All the added sections.
+    # @api public
+    def add(section)
+      @list[section.name] = section
+    end
+
+    # Returns a section based on its verb and url
+    #
+    # @param [String] verb The request method (GET, POST, PUT, DELETE)
+    # @param [String] url The url of the section you are looking for.
+    # @return [Nil, Kanpachi::Section] The found section.
+    #
+    # @api public
+    def find(name)
+      @list[name]
+    end
+  end
+end

data/lib/kanpachi/templates/.gitignore

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

data/lib/kanpachi/templates/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'kanpachi', git: 'git@github.com:kamui/kanpachi.git'
+gem 'roar'

data/lib/kanpachi/templates/api/api.rb

@@ -0,0 +1,17 @@
+api 'MyAPI' do
+  title 'REST API v1.0 Resources'
+  description 'This describes the resources that make up the official API'
+  host 'api.example.com'
+
+  section 'Users' do
+    description 'Users are users of the system.'
+  end
+
+  section 'Posts' do
+    description 'Posts are blog posts from users.'
+  end
+
+  section 'Comments' do
+    description 'Comments are made by users on blog posts.'
+  end
+end

data/lib/kanpachi/templates/api/errors.rb

@@ -0,0 +1,13 @@
+api 'MyAPI' do
+  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
+end

data/lib/kanpachi/templates/api/posts.rb

@@ -0,0 +1,32 @@
+require 'representable/json/collection'
+
+api 'MyAPI' do
+  section 'Posts' do
+    resource :get, '/posts' do
+      name 'List Posts'
+      description <<-TEXT
+Return a collection of __blog posts__. Sort order defaults to _most recently published_.
+TEXT
+      versions '1.0'
+      ssl true
+      formats :json
+
+      params do
+        optional do
+          integer :size, max: 100, doc: 'The number of results to return. (max: 100)', example: 10
+        end
+      end
+
+      response do
+        status 200
+        header 'Content-Type', 'application/json'
+        representation do
+          include Representable::JSON::Collection
+          property :title, type: String, doc: 'Title of the post', example: 'APIs Run Amok!'
+          property :body, type: String, doc: 'The Body of the post ', example: 'I love me some API!'
+          property :created_at, type: DateTime, doc: 'When the post was created.'
+        end
+      end
+    end
+  end
+end

data/lib/kanpachi/templates/api/users.rb

@@ -0,0 +1,38 @@
+api 'MyAPI' do
+  section 'Users' do
+    resource :post, '/users' do
+      name 'Create a user'
+      description <<-TEXT
+__Creates a user__. `User`'s must provide a valid email address. Upon registration,
+an activation email will be sent to the user.
+TEXT
+      versions '1.0'
+      ssl true
+      formats :json
+
+      params do
+        required do
+          string :email, doc: 'Email address', example: 'user@example.com'
+          string :full_name, doc: 'Full name', example: 'Jack Chu'
+          string :password, min_length: 8, doc: 'The password must be 8 characters minumum', example: 'notPassword'
+          string :password_confirmation, min_length: 8, doc: 'Password (confirm)'
+          integer :age, doc: 'Age', example: 21
+        end
+
+        optional do
+          boolean :newsletter, doc: 'Do you want our weekly newsletter?', default: false
+        end
+      end
+
+      response do
+        status 201
+        header 'Content-Type', 'application/json'
+        representation do
+          property :message, type: String, doc: 'Thank you message for the user.', example: 'Thanks for registering!'
+          collection :roles, doc: 'The authorization roles this user has.', example: ['member', 'superuser']
+          hash :preferences, doc: 'The preferences for this user.', example: {remember_me: true, newsletter: false}
+        end
+      end
+    end
+  end
+end

data/lib/kanpachi/version.rb

@@ -0,0 +1,3 @@
+module Kanpachi
+  VERSION = '0.0.1'
+end

data/lib/kanpachi.rb

@@ -0,0 +1,7 @@
+require 'kanpachi/version'
+require 'kanpachi/api'
+require 'kanpachi/dsl'
+require 'kanpachi/markdown'
+
+module Kanpachi
+end

data/spec/api_list_spec.rb

@@ -0,0 +1,55 @@
+require_relative 'spec_helper'
+
+describe Kanpachi::APIList do
+  before do
+    Kanpachi::APIList.clear
+  end
+
+  subject do
+    Kanpachi::APIList
+  end
+
+  it 'initializes empty' do
+    subject.all.must_be_empty
+  end
+
+  describe 'Populated API' do
+    let(:myapp_api) do
+      Kanpachi::API.new('MyApp')
+    end
+
+    it 'returns a hash of the internal list, with API names as the key and a Section object as the value' do
+      Kanpachi::APIList.add(myapp_api)
+      subject.to_hash.keys.must_include 'MyApp'
+      subject.to_hash['MyApp'].must_equal myapp_api
+    end
+
+    it 'returns an array of Section objects' do
+      Kanpachi::APIList.add(myapp_api)
+      subject.all.must_include myapp_api
+    end
+
+    it 'adds a API' do
+      subject.add(myapp_api)
+      subject.all.must_include myapp_api
+    end
+
+    it 'deletes a API' do
+      subject.add(myapp_api)
+      subject.delete(myapp_api.name)
+      subject.all.wont_include myapp_api
+    end
+
+    it 'finds a API by name' do
+      Kanpachi::APIList.add(myapp_api)
+      subject.find('MyApp').must_equal myapp_api
+    end
+  end
+
+  it 'clears all APIs' do
+    myapp_api = Kanpachi::API.new('MyApp')
+    Kanpachi::APIList.add(myapp_api)
+    subject.clear
+    subject.all.size.must_equal 0
+  end
+end

data/spec/api_spec.rb

@@ -0,0 +1,56 @@
+require_relative 'spec_helper'
+
+describe Kanpachi::API do
+  subject do
+    Kanpachi::API.new('MockApi')
+  end
+
+  it 'returns the API name' do
+    subject.name.must_equal 'MockApi'
+  end
+
+  it 'initializes resources as a Kanpachi::ResourceList' do
+    subject.resources.class.must_equal Kanpachi::ResourceList
+  end
+
+  it 'initializes errors as a Kanpachi::ErrorList' do
+    subject.errors.class.must_equal Kanpachi::ErrorList
+  end
+
+  it 'initializes sections as a Kanpachi::SectionList' do
+    subject.sections.class.must_equal Kanpachi::SectionList
+  end
+
+  it 'has a title' do
+    subject.title = 'The Mock API!'
+    subject.title.must_equal 'The Mock API!'
+  end
+
+  it 'has a description' do
+    subject.description = 'API for testing'
+    subject.description.must_equal 'API for testing'
+  end
+
+  it 'has a host' do
+    subject.description = 'API for testing'
+    subject.description.must_equal 'API for testing'
+  end
+
+  it 'has sections' do
+    section = Kanpachi::Section.new('Stuff')
+    subject.sections.add(section)
+    subject.sections.find('Stuff').must_equal section
+  end
+
+  it 'has errors' do
+    error = Kanpachi::Error.new(:not_found)
+    subject.errors.add(error)
+    subject.errors.find(:not_found).must_equal error
+  end
+
+  it 'has resources' do
+    resource = Kanpachi::Resource.new(:post, '/posts')
+    subject.resources.add(resource)
+    subject.resources.find(:post, '/posts').must_equal resource
+  end
+end

data/spec/dsl/api_spec.rb

@@ -0,0 +1,74 @@
+require_relative '../spec_helper'
+
+describe Kanpachi::DSL::API do
+  subject do
+    Kanpachi::DSL::API.new(my_api)
+  end
+
+  let(:my_api) do
+    extend Kanpachi::DSL
+    api 'MyApp' do
+      title 'My App'
+    end
+  end
+
+  it 'sets the title' do
+    subject.title 'My Little API'
+    my_api.title.must_equal 'My Little API'
+  end
+
+  it 'sets the description' do
+    subject.description 'Just for testing'
+    my_api.description.must_equal 'Just for testing'
+  end
+
+  it 'sets the host' do
+    subject.host 'api.localhost.dev'
+    my_api.host.must_equal 'api.localhost.dev'
+  end
+
+  it 'adds a new error to the error list' do
+    error = subject.error :not_authorized
+    my_api.errors.find(:not_authorized).must_equal error
+  end
+
+  it 'raises a Kanpachi::ErrorList::DuplicateError if error name already exists' do
+    subject.error :not_found
+    proc do
+      subject.error :not_found do
+        response do
+          status 400
+        end
+      end
+    end.must_raise Kanpachi::ErrorList::DuplicateError
+  end
+
+  it 'adds a new section to the section list' do
+    subject.section 'Posts'
+    my_api.sections.find('Posts').name.must_equal 'Posts'
+  end
+
+  it 'reopens a section with the same name in the section list' do
+    subject.section 'Users'
+    section = subject.section 'Users' do
+      description 'Users Section'
+    end
+    my_api.sections.find('Users').must_equal section
+  end
+
+  it 'adds a new resource to the resource list' do
+    resource = subject.resource :get, '/posts'
+    my_api.resources.find(:get, '/posts').must_equal resource
+  end
+
+  it 'raises a Kanpachi::ResourceList::DuplicateResource if resource route already exists' do
+    subject.resource :get, '/users'
+    proc do
+      subject.resource :get, '/users' do
+        response do
+          status 400
+        end
+      end
+    end.must_raise Kanpachi::ResourceList::DuplicateResource
+  end
+end

data/spec/dsl/error_spec.rb

@@ -0,0 +1,38 @@
+require_relative '../spec_helper'
+
+describe Kanpachi::DSL::Error do
+  before do
+    Kanpachi::APIList.clear
+  end
+
+  subject do
+    Kanpachi::DSL::Error.new(not_found_error, api_dsl)
+  end
+
+  let(:not_found_error) do
+    Kanpachi::Error.new(:not_found_error)
+  end
+
+  let(:api_dsl) do
+    Kanpachi::DSL::API.new(my_api)
+  end
+
+  let(:my_api) do
+    extend Kanpachi::DSL
+    api 'MyApp' do
+      title 'My App'
+    end
+  end
+
+  it 'sets the description' do
+    subject.description 'Just for testing'
+    not_found_error.description.must_equal 'Just for testing'
+  end
+
+  it 'sets the response' do
+    subject.response do
+      status 201
+    end
+    not_found_error.response.status.must_equal 201
+  end
+end