useless-doc 0.1.0

data/lib/useless/doc/ui/godel.rb

@@ -0,0 +1,92 @@
+require 'mustache'
+require 'forwardable'
+
+require 'useless/doc/ui'
+
+module Useless
+  module Doc
+    module UI
+      class Godel < ::Mustache
+        include UI
+
+        def initialize(resource)
+          @resource = Godel::Resource.new(resource)
+        end
+
+        class Resource
+          extend Forwardable
+
+          def_delegators :@resource, :path, :description
+
+          def initialize(resource)
+            @resource = resource
+          end
+
+          def actions
+            @resource.actions.map{ |action| Godel::Action.new(action) }
+          end
+        end
+
+        class Action
+          extend Forwardable
+
+          def_delegators :@action, :description, :method
+
+          def initialize(action)
+            @action = action
+          end
+
+          def authentication_requirement
+            @action.authentication_required ?
+              'Authentication Required' :
+              'Authenication Not Required'
+          end
+
+          def request
+            Godel::Request.new(@action.request)
+          end
+
+          def response
+            Godel::Response.new(@action.response)
+          end
+        end
+
+        class Request
+          extend Forwardable
+
+          def_delegators :@request, :parameters, :headers, :body
+
+          def initialize(request)
+            @request = request
+          end
+
+          def parameters?
+            parameters.any?
+          end
+
+          def headers?
+            headers.any?
+          end
+        end
+
+        class Response
+          extend Forwardable
+
+          def_delegators :@response, :statuses, :headers, :body
+
+          def initialize(response)
+            @response = response
+          end
+
+          def statuses?
+            statuses.any?
+          end
+
+          def headers?
+            headers.any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/ui.rb

@@ -0,0 +1,37 @@
+require 'forwardable'
+require 'mustache'
+
+module Useless
+  module Doc
+    module UI
+      def self.included(base)
+        base.instance_eval do
+          extend ClassMethods
+          self.template_file = dir + 'template.mustache'
+
+          extend Forwardable
+          def_delegators :@resource, :path, :description, :actions
+        end
+      end
+
+      module ClassMethods
+        def html(resource)
+          new(resource).render
+        end
+
+        def css
+          File.read(dir + 'stylesheet.css')
+        end
+
+        def dir
+          key = Mustache.underscore(name.split('::').last)
+          File.dirname(__FILE__) + "/ui/#{key}/"
+        end
+      end
+
+      def initialize(resource)
+        @resource = resource
+      end
+    end
+  end
+end

data/lib/useless/doc/version.rb

@@ -0,0 +1,5 @@
+module Useless
+  module Doc
+    VERSION = '0.1.0'
+  end
+end

data/lib/useless/doc.rb

@@ -0,0 +1,4 @@
+module Useless
+  module Doc
+  end
+end

data/spec/documents/twonk.json

@@ -0,0 +1,106 @@
+{
+  "path": "/twonks/:id",
+  "description": "The most critical aspect.",
+  "actions": [
+    {
+      "description": "Retrieve a representation of an individual twonk.",
+      "method": "GET",
+      "authentication_required": false,
+      "request": {
+        "parameters": [
+          {
+            "type": "path",
+            "key": "id",
+            "required": true,
+            "description": "The ID of the desired twonk."
+          },
+          {
+            "type": "query",
+            "key": "werp",
+            "required": false,
+            "default": 12,
+            "description": "Self-explanatory."
+          }
+        ],
+        "headers": [
+          {
+            "key": "User-Agent",
+            "description": "The thingy you're using."
+          }
+        ]
+      },
+      "response": {
+        "statuses": [
+          {
+            "code": 200,
+            "description": "The specified twonk was retrieved successfully."
+          },
+          {
+            "code": 404,
+            "description": "A twonk with the specified ID could not be found."
+          }
+        ],
+        "body": {
+          "content_type": "application/json",
+          "attributes": [
+            {
+              "key": "name",
+              "type": "string",
+              "required": true,
+              "description": "The name of the twonk."
+            },
+            {
+              "key": "created_by",
+              "type": "object",
+              "required": true,
+              "description": "The short name of the user who created the twonk."
+            }
+          ]
+        }
+
+      }
+    },
+
+    {
+      "description": "Update a twonk.",
+      "method": "PUT",
+      "authentication_required": true,
+      "request": {
+        "parameters": [
+          {
+            "type": "path",
+            "key": "id",
+            "required": true,
+            "description": "The ID of the twonk to be updated."
+          }
+        ],
+        "body": {
+          "content_type": "application/x-www-form-urlencoded",
+          "attributes": [
+            {
+              "key": "name",
+              "type": "string",
+              "required": true,
+              "description": "The name of the twonk."
+            },
+            {
+              "key": "hoinked_by",
+              "type": "number",
+              "required": false,
+              "default": 3,
+              "description": "The ID of the person who hoinked this twonk."
+            }
+          ]
+        }
+      },
+      "response": {
+        "statuses": [
+          {
+            "code": 201,
+            "description": "The specified twonk was updated successfully."
+          }
+        ]
+      }
+    }
+  ]
+}

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require File.dirname(__FILE__) + '/../lib/useless/doc'
+
+RSpec.configure do |config|
+  config.order = :rand
+end
+
+def load_document(name)
+  filename = File.dirname(__FILE__) + "/documents/#{name}"
+  File.new(filename)
+end

data/spec/useless/doc/dsl_spec.rb

@@ -0,0 +1,71 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+require 'rack/test'
+require 'useless/doc/dsl'
+
+describe Useless::Doc::DSL do
+  describe '.build' do
+    it 'should provide a terse DSL for building resource documentation' do
+      resource = Useless::Doc::DSL::Resource.build do
+        path '/widgets'
+        description 'The entire collection of widgets'
+
+        get 'Returns a full listing of the collection' do
+          authentication_required false
+
+          request do
+            parameter 'page', 'The page of widgets that you\'d like', 
+              type: :query, required: false, default: 1
+
+            header 'X-Twiddle', 'The twiddle threshold.'
+          end
+
+          response do
+            status 200, 'The widgets were appropriately returned'
+            status 404, 'All the widgets are gone!!!!!'
+
+            header 'X-Twonk', 'The twonk coefficient.'
+
+            body do
+              content_type 'application/json'
+
+              attribute 'name', 'The name of the widget', required: true
+              attribute 'age', 'The age of the widget. If missing, the widget was never born',
+                type: :number, required: false
+            end
+          end
+        end
+
+        post do
+          authentication_required true
+
+          description 'Creates a new widget'
+
+          request do
+            body do
+              content_type 'application/json'
+
+              attribute 'name', 'The name of the widget', required: true
+              attribute 'age', 'The age of the widget', type: :number, required: false, default: 42
+            end
+          end
+
+          response do
+            status 201, 'The widget was successfully created'
+            status 422, 'The widget couldn\'t be created because name was missing'
+          end
+        end
+      end
+
+      resource.description.should == 'The entire collection of widgets'
+      resource.actions[0].method.should == 'GET'
+      resource.actions[0].request.headers[0].description.should == 'The twiddle threshold.'
+      resource.actions[0].response.statuses[0].code.should == 200
+      resource.actions[1].method.should == 'POST'
+      resource.actions[1].description.should == 'Creates a new widget'
+      resource.actions[1].request.body.content_type.should == 'application/json'
+      resource.actions[1].request.body.attributes[0].key.should == 'name'
+      resource.actions[1].response.statuses[1].description.should == 'The widget couldn\'t be created because name was missing'
+    end
+  end
+end

data/spec/useless/doc/proxy_spec.rb

@@ -0,0 +1,48 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+require 'rack/test'
+require 'useless/doc/proxy'
+require 'useless/doc/ui/godel'
+
+describe Useless::Doc::Proxy do
+  include Rack::Test::Methods
+
+  def app
+    @app ||= begin
+      ui = Useless::Doc::UI::Godel
+      Useless::Doc::Proxy.new(ui)
+    end
+  end
+
+  describe 'as a Rack application' do
+    it 'should proxy GET requests as an OPTIONS request to the corresponding API resource.' do
+      app.should_receive(:retrieve_resource).
+        with('http://some-api.granmal.com/some/resource').
+        and_return('{ "some": "response" }')
+
+      get 'http://some-api.doc.granmal.com/some/resource'
+      last_response.should be_ok
+    end
+
+    it 'should return a 404 if the proxy call returns nothing' do
+      app.should_receive(:retrieve_resource).
+        with('http://some-api.granmal.com/some/non-existant/resource').
+        and_return(nil)
+
+      get 'http://some-api.doc.granmal.com/some/non-existant/resource'
+      last_response.should be_not_found
+    end
+  end
+
+  describe '.transform_url' do
+    it 'should drop the \'doc\' subdomain from the url for the \'io\' TLD' do
+      url = Useless::Doc::Proxy.transform_url 'http://some-api.doc.useless.io/some/resource'
+      url.should == 'http://some-api.useless.io/some/resource'
+    end
+
+    it 'should drop the \'doc\' subdomain from the url for the \'dev\' TLD' do
+      url = Useless::Doc::Proxy.transform_url 'http://some-api.doc.useless.dev/some/resource'
+      url.should == 'http://some-api.useless.dev/some/resource'
+    end
+  end
+end

data/spec/useless/doc/serialization/dump_spec.rb

@@ -0,0 +1,116 @@
+require File.dirname(__FILE__) + '/../../../spec_helper'
+
+require 'useless/doc/serialization/dump'
+
+describe Useless::Doc::Serialization::Dump do
+  describe '.hash_to_json' do
+    it 'should convert a hash to a JSON document' do
+      hash = Useless::Doc::Serialization::Dump.hash_to_json({'abc' => 123})
+      hash.should == '{"abc":123}'
+    end
+
+    it 'should act as an identity if a JSON document is specified' do
+      json = '{"abc":123}'
+      Useless::Doc::Serialization::Dump.hash_to_json(json).should == json
+    end
+  end
+
+  describe '.resource' do
+    it 'should convert the specified Doc::Resource instance into JSON' do
+      get_parameter = Useless::Doc::Request::Parameter.new \
+        type:         Useless::Doc::Request::Parameter::Type::PATH,
+        key:          'page',
+        required:     false,
+        default:      1,
+        description:  'The number of the page of twiddles.'
+
+      get_request_header = Useless::Doc::Header.new \
+        key:          'Content',
+        description:  'The type of content.'
+
+      get_request = Useless::Doc::Request.new \
+        parameters: [get_parameter],
+        headers:    [get_request_header],
+        body:       nil
+
+      get_status = Useless::Doc::Response::Status.new \
+        code:         200,
+        description:  'The list was successfully returned.'
+
+      get_response_header = Useless::Doc::Header.new \
+        key:          'Type',
+        description:  'The response type.'
+
+      get_response_body_attribute = Useless::Doc::Body::Attribute.new \
+        key:          'name',
+        type:         'string',
+        required:     true,
+        default:      nil,
+        description:  'The name of the twiddle.'
+
+      get_response_body = Useless::Doc::Body.new \
+        content_type: 'application/json',
+        attributes:   [get_response_body_attribute] 
+
+      get_response = Useless::Doc::Response.new \
+        statuses: [get_status],
+        headers:  [get_response_header],
+        body:     get_response_body
+
+      get = Useless::Doc::Action.new \
+        description:              'See a whole list of twiddles.',
+        method:                   Useless::Doc::Action::Method::GET,
+        authentication_required:  false,
+        request:                  get_request,
+        response:                 get_response
+
+      resource = Useless::Doc::Resource.new \
+        path:         '/twiddles',
+        description:  'The full lot of twiddles.',
+        actions:      [get]
+
+      json = Useless::Doc::Serialization::Dump.resource(resource)
+      hash = Useless::Doc::Serialization::Load.json_to_hash(json)
+
+      hash['path'].should == '/twiddles'
+      hash['description'].should == 'The full lot of twiddles.'
+
+      get_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['actions'][0])
+      get_hash['description'].should == 'See a whole list of twiddles.'
+      get_hash['method'].should == 'GET'
+      get_hash['authentication_required'].should be_false
+
+      get_request_hash = Useless::Doc::Serialization::Load.json_to_hash(get_hash['request'])
+      get_request_paramter_hash = Useless::Doc::Serialization::Load.json_to_hash(get_request_hash['parameters'][0])
+      get_request_paramter_hash['type'].should == 'path'
+      get_request_paramter_hash['key'].should == 'page'
+      get_request_paramter_hash['required'].should == false
+      get_request_paramter_hash['default'].should == 1
+      get_request_paramter_hash['description'].should == 'The number of the page of twiddles.'
+
+      get_request_header_hash = Useless::Doc::Serialization::Load.json_to_hash(get_request_hash['headers'][0])
+      get_request_header_hash['key'].should == 'Content'
+      get_request_header_hash['description'].should == 'The type of content.'
+
+      get_response_hash = Useless::Doc::Serialization::Load.json_to_hash(get_hash['response'])
+      get_response_status_hash = Useless::Doc::Serialization::Load.json_to_hash(get_response_hash['statuses'][0])
+      get_response_status_hash['code'].should == 200
+      get_response_status_hash['description'].should == 'The list was successfully returned.'
+
+      get_response_header_hash = Useless::Doc::Serialization::Load.json_to_hash(get_response_hash['headers'][0])
+      get_response_header_hash['key'].should == 'Type'
+      get_response_header_hash['description'].should == 'The response type.'
+
+      get_response_body_hash = Useless::Doc::Serialization::Load.json_to_hash(get_response_hash['body'])
+      get_response_body_hash['content_type'].should == 'application/json'
+
+      get_request_body_attribute_hash = Useless::Doc::Serialization::Load.json_to_hash(get_response_body_hash['attributes'][0])
+      get_request_body_attribute_hash['key'].should == 'name'
+      get_request_body_attribute_hash['type'].should == 'string'
+      get_request_body_attribute_hash['required'].should == true
+      get_request_body_attribute_hash['default'].should be_nil
+      get_request_body_attribute_hash['description'].should == 'The name of the twiddle.'
+    end
+  end
+
+end

data/spec/useless/doc/serialization/load_spec.rb

@@ -0,0 +1,99 @@
+require File.dirname(__FILE__) + '/../../../spec_helper'
+
+require 'useless/doc/serialization/load'
+
+describe Useless::Doc::Serialization::Load do
+  describe '.json_to_hash' do
+    it 'should convert a JSON document to a hash' do
+      hash = Useless::Doc::Serialization::Load.json_to_hash('{ "abc": 123 }')
+      hash.should be_a Hash
+      hash['abc'].should == 123
+    end
+
+    it 'should act as an identity if a hash is specified' do
+      hash = { abc: 123 }
+      Useless::Doc::Serialization::Load.json_to_hash(hash).should == hash
+    end
+  end
+
+  describe '.resource' do
+    it 'should parse the specified JSON into a model hierarchy' do
+      document = load_document('twonk.json')
+      resource = Useless::Doc::Serialization::Load.resource document.read
+
+      resource.should be_a Useless::Doc::Resource
+      resource.path.should == '/twonks/:id'
+      resource.description.should == 'The most critical aspect.'
+
+      get = resource.actions.first
+      get.should be_a Useless::Doc::Action
+      get.description.should == 'Retrieve a representation of an individual twonk.'
+      get.method.should == 'GET'
+      get.authentication_required.should == false
+
+      get.request.parameters[0].type.should == 'path'
+      get.request.parameters[0].key.should == 'id'
+      get.request.parameters[0].required.should == true
+      get.request.parameters[0].default.should be_nil
+      get.request.parameters[0].description.should == 'The ID of the desired twonk.'
+
+      get.request.parameters[1].type.should == 'query'
+      get.request.parameters[1].key.should == 'werp'
+      get.request.parameters[1].required.should == false
+      get.request.parameters[1].default.should == 12
+      get.request.parameters[1].description.should == 'Self-explanatory.'
+
+      get.request.headers[0].key.should == 'User-Agent'
+      get.request.headers[0].description.should == 'The thingy you\'re using.'
+
+      get.response.statuses[0].code.should == 200
+      get.response.statuses[0].description.should == 'The specified twonk was retrieved successfully.'
+
+      get.response.statuses[1].code.should == 404
+      get.response.statuses[1].description.should == 'A twonk with the specified ID could not be found.'
+
+      get.response.body.content_type.should == 'application/json'
+
+      get.response.body.attributes[0].key.should == 'name'
+      get.response.body.attributes[0].type.should == 'string'
+      get.response.body.attributes[0].required.should be_true
+      get.response.body.attributes[0].default.should be_nil
+      get.response.body.attributes[0].description.should == 'The name of the twonk.'
+
+      get.response.body.attributes[1].key.should == 'created_by'
+      get.response.body.attributes[1].type.should == 'object'
+      get.response.body.attributes[1].required.should be_true
+      get.response.body.attributes[1].default.should be_nil
+      get.response.body.attributes[1].description.should == 'The short name of the user who created the twonk.'
+
+      put = resource.actions.last
+      put.should be_a Useless::Doc::Action
+      put.description.should =='Update a twonk.'
+      put.method.should == 'PUT'
+      put.authentication_required.should == true
+
+      put.request.parameters[0].type.should == 'path'
+      put.request.parameters[0].key.should == 'id'
+      put.request.parameters[0].required.should == true
+      put.request.parameters[0].default.should be_nil
+      put.request.parameters[0].description.should == 'The ID of the twonk to be updated.'
+
+      put.request.body.content_type.should == 'application/x-www-form-urlencoded'
+
+      put.request.body.attributes[0].key.should == 'name'
+      put.request.body.attributes[0].type.should == 'string'
+      put.request.body.attributes[0].required.should be_true
+      put.request.body.attributes[0].default.should be_nil
+      put.request.body.attributes[0].description.should == 'The name of the twonk.'
+
+      put.request.body.attributes[1].key.should == 'hoinked_by'
+      put.request.body.attributes[1].type.should == 'number'
+      put.request.body.attributes[1].required.should be_false
+      put.request.body.attributes[1].default.should == 3
+      put.request.body.attributes[1].description.should == 'The ID of the person who hoinked this twonk.'
+
+      put.response.statuses[0].code.should == 201
+      put.response.statuses[0].description.should == 'The specified twonk was updated successfully.'
+    end
+  end
+end

data/spec/useless/doc/sinatra_spec.rb

@@ -0,0 +1,64 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+require 'sinatra/base'
+require 'useless/doc/sinatra'
+
+describe Useless::Doc::Sinatra do
+  class DocApp < Sinatra::Base
+    register Useless::Doc::Sinatra
+
+    doc '/some-resources' do
+      get 'Get all of these resources' do
+        request do
+          parameter 'since', 'Only resources after this date.'
+        end
+
+        response do
+          body do
+            attribute 'name', 'The name of the resource.'
+          end
+        end
+      end
+
+      post 'Make a new resource' do
+        request do
+          body do
+            attribute 'name', 'The name of the resource.'
+          end
+        end
+
+        response do
+          status 201, 'The resource was successfully created.'
+        end
+      end
+    end
+
+    get '/some-resources' do
+      []
+    end
+
+    post '/some-resources' do
+      201
+    end
+  end
+
+  include Rack::Test::Methods
+
+  def app
+    DocApp
+  end
+
+  it 'should serve documentation for the documented resource' do
+    options 'http://some-api.granmal.com/some-resources'
+    resource = Useless::Doc::Serialization::Load.resource(last_response.body)
+
+    get = resource.actions.find { |action| action.method == Useless::Doc::Action::Method::GET }
+    get.description.should == 'Get all of these resources'
+    get.request.parameters.first.key.should == 'since'
+
+    post = resource.actions.find { |action| action.method == Useless::Doc::Action::Method::POST }
+    post.description.should == 'Make a new resource'
+    post.response.statuses.first.code.should == 201
+  end
+
+end

data/useless-doc.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'useless/doc/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'useless-doc'
+  gem.version       = Useless::Doc::VERSION
+  gem.authors       = 'Kevin Hyland'
+  gem.email         = 'khy@me.com'
+  gem.description   = 'For parsing and serving Useless documentation.'
+  gem.summary       = 'For parsing and serving Useless documentation.'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^spec/})
+
+  gem.add_dependency 'oj'
+  gem.add_dependency 'rack'
+  gem.add_dependency 'typhoeus'
+  gem.add_dependency 'low'
+  gem.add_dependency 'sinatra'
+  gem.add_dependency 'mustache'
+
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rack-test'
+end