useless-doc 0.2.3 → 0.3.0

data/spec/documents/domain.json

@@ -0,0 +1,17 @@
+{
+  "name": "Useless",
+  "url": "http://useless.io",
+  "description": "A collection of useless APIs.",
+  "apis": [
+    {
+      "name": "The Jah API",
+      "url": "http://jah.useless.io",
+      "description": "Jah, jah, jah."
+    },
+    {
+      "name": "The Twonk API",
+      "url": "http://twonk.useless.io",
+      "description": "TWONK!!!"
+    }
+  ]
+}

data/spec/useless/doc/client_spec.rb

@@ -0,0 +1,59 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+require 'useless/doc/client'
+
+describe Useless::Doc::Client::Standard do
+  before(:each) do
+    @client = Useless::Doc::Client.standard
+    @client.instance_variable_set(:@cache, {})
+  end
+
+  it 'should make a normal request if the cache is empty.' do
+    Typhoeus.should_receive(:options).
+      with('http://some-api.granmal.com/some/resource', headers: { 'Accept' => 'application/json' }).
+      and_return(mock(:response, response_code: 200, response_body: load_document('twonk.json').read))
+
+    resource = @client.get('http://some-api.granmal.com/some/resource')
+    resource.path.should == '/twonks/:id'
+  end
+
+  it 'should return an API if that is what\'s returned' do
+    Typhoeus.should_receive(:options).
+      with('http://some-api.granmal.com/', headers: { 'Accept' => 'application/json' }).
+      and_return(mock(:response, response_code: 200, response_body: load_document('api.json').read))
+
+    api = @client.get('http://some-api.granmal.com/')
+    api.url.should == 'twonk.useless.io'
+  end
+
+  it 'should make a request with a cache control header if there is a cache hit.' do
+    now = Time.now
+    Time.should_receive(:now).once.and_return(now)
+
+    Typhoeus.should_receive(:options).once.
+      with('http://some-api.granmal.com/some/resource', headers: { 'Accept' => 'application/json' }).
+      and_return(mock(:response, response_code: 200, response_body: load_document('twonk.json').read))
+
+    Typhoeus.should_receive(:options).once.
+      with('http://some-api.granmal.com/some/resource', headers: { 'Accept' => 'application/json', 'If-Modified-Since' => now.httpdate}).
+      and_return(mock(:response, response_code: 304, response_body: ''))
+
+    @client.get('http://some-api.granmal.com/some/resource')
+    resource = @client.get('http://some-api.granmal.com/some/resource')
+    resource.path.should == '/twonks/:id'
+  end
+end
+
+describe Useless::Doc::Client::Stub do
+  it 'should serve files from the spec/documents directory' do
+    client = Useless::Doc::Client.stub
+    resource = client.get('http://anything.useless.io/twonk')
+    resource.path.should == '/twonks/:id'
+  end
+
+  it 'should return nil if the corresponding file doesn\'t exist' do
+    client = Useless::Doc::Client.stub
+    resource = client.get('http://anything.useless.io/nonexistant')
+    resource.should be_nil
+  end
+end

data/spec/useless/doc/dsl_spec.rb

@@ -5,10 +5,35 @@ require 'rack/test'
 require 'useless/doc'
 require 'useless/doc/dsl'
 
-describe Useless::Doc::DSL do
+describe Useless::Doc::DSL::Domain do
+  describe '.build' do
+    it 'should provide a DSL for building a domain (through Useless::Doc.domain)' do
+      domain = Useless::Doc.domain 'useless.io' do
+        url 'http://useless.io'
+        description 'A collection of useless APIs.'
+
+        api 'Twonk' do
+          url 'twonk.useless.io'
+          description 'Twonk stuff'
+        end
+      end
+
+      domain.name.should == 'useless.io'
+      domain.url.should == 'http://useless.io'
+      domain.description.should == 'A collection of useless APIs.'
+
+      domain.apis.first.name.should == 'Twonk'
+      domain.apis.first.url.should == 'twonk.useless.io'
+      domain.apis.first.description.should == 'Twonk stuff'
+    end
+  end
+end
+
+describe Useless::Doc::DSL::API do
   describe '.build' do
     it 'should provide a terse DSL for building API documentation (through Useless::Doc.api)' do
-      api = Useless::Doc.api 'widget.useless.io' do
+      api = Useless::Doc.api 'Widget API' do
+        url 'widget.useless.io'
         description 'The canonical source of worldwide widgets.'
 
         resource('/widgets').description 'The whole kit and kaboodle.'
@@ -64,6 +89,7 @@ describe Useless::Doc::DSL do
         timestamp '2013-01-12 12:44 AM'
       end
 
+      api.name.should == 'Widget API'
       api.url.should == 'widget.useless.io'
       api.description.should == 'The canonical source of worldwide widgets.'
       api.timestamp.should == Time.parse('2013-01-12 12:44 AM')

data/spec/useless/doc/rack/{stylesheet_spec.rb → css_spec.rb}

@@ -1,10 +1,10 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
 
 require 'rack/test'
-require 'useless/doc/rack/stylesheet'
+require 'useless/doc/rack/css'
 require 'useless/doc/ui/godel'
 
-describe Useless::Doc::Rack::Stylesheet do
+describe Useless::Doc::Rack::CSS do
   include Rack::Test::Methods
 
   def base_app
@@ -16,16 +16,10 @@ describe Useless::Doc::Rack::Stylesheet do
   def app
     @app ||= lambda do |env|
       env['useless.doc.ui'] = Useless::Doc::UI::Godel
-      Useless::Doc::Rack::Stylesheet.new(base_app).call(env)
+      Useless::Doc::Rack::CSS.new(base_app).call(env)
     end
   end
 
-  it 'should raise an error if a UI is not specified' do
-    app = Useless::Doc::Rack::Stylesheet.new(base_app)
-    request = Rack::MockRequest.new(app)
-    lambda { request.get('http://some-api.granmal.com/doc.css') }.should raise_error(RuntimeError, 'No UI specified.')
-  end
-
   it 'should proxy requests if the path is not doc.css' do
     get 'http://some-api.granmal.com/not/doc.css'
     last_response.body.should == 'Not a stylesheet request.'

data/spec/useless/doc/rack/html_spec.rb

@@ -0,0 +1,39 @@
+require File.dirname(__FILE__) + '/../../../spec_helper'
+
+require 'rack/test'
+require 'useless/doc/ui/godel'
+require 'useless/doc/core/api'
+require 'useless/doc/rack/html'
+
+describe Useless::Doc::Rack::HTML do
+  include Rack::Test::Methods
+
+  before(:all) do
+    @ui = Useless::Doc::UI::Godel.new(nil)
+    @subject = Useless::Doc::Core::API.new
+  end
+
+  def app
+    @app ||= lambda do |env|
+      env['useless.doc.ui'] = @ui
+      env['useless.doc.subject'] = @subject
+
+      Useless::Doc::Rack::HTML.call(env)
+    end
+  end
+
+  it 'should transform the subject to HTML via the specified UI' do
+    @ui.should_receive(:html).with(@subject).and_return('html')
+
+    get 'http://some-api.doc.useless.io/some/resource'
+    last_response.should be_ok
+    last_response.body.should == 'html'
+  end
+
+  it 'should return a 404 if the UI cannot render the HTML' do
+    @ui.should_receive(:html).with(@subject).and_return(nil)
+
+    get 'http://some-api.doc.useless.io/some/resource'
+    last_response.should be_not_found
+  end
+end

data/spec/useless/doc/rack/subject_spec.rb

@@ -0,0 +1,44 @@
+require File.dirname(__FILE__) + '/../../../spec_helper'
+
+require 'rack/test'
+require 'useless/doc/rack/subject'
+
+describe Useless::Doc::Rack::Subject do
+  include Rack::Test::Methods
+
+  def app
+    @app ||= lambda do |env|
+      base_app = lambda do |env|
+        [200, {'Content-Type' => 'text/plain'}, [env['useless.doc.subject']]]
+      end
+
+      env['useless.doc.url'] = 'some.api.com'
+      Useless::Doc::Rack::Subject.new(base_app).call(env)
+    end
+  end
+
+  it 'should retrieve the subject from the stub client in a non-production environment' do
+    Useless::Doc::Client.stub.should_receive(:get).with('some.api.com').and_return('test subject')
+    get 'some.doc.api.com'
+    last_response.should be_ok
+    last_response.body.should == 'test subject'
+  end
+
+  it 'should retrieve the subject from the standard client in a production environment' do
+    begin
+      ENV['RACK_ENV'] = 'production'
+      Useless::Doc::Client.standard.should_receive(:get).with('some.api.com').and_return('production subject')
+      get 'some.doc.api.com'
+      last_response.should be_ok
+      last_response.body.should == 'production subject'
+    ensure
+      ENV['RACK_ENV'] = 'test'
+    end
+  end
+
+  it 'should return a 404 if no subject is returned' do
+    Useless::Doc::Client.stub.should_receive(:get).with('some.api.com').and_return(nil)
+    get 'some.doc.api.com'
+    last_response.should be_not_found
+  end
+end

data/spec/useless/doc/rack/ui_spec.rb

@@ -9,7 +9,7 @@ describe Useless::Doc::Rack::UI do
   def app
     @app ||= begin
       base_app = lambda do |env|
-        [200, {'Content-Type' => 'text/plain'}, [env['useless.doc.ui'].name]]
+        [200, {'Content-Type' => 'text/plain'}, [env['useless.doc.ui'].class.name]]
       end
 
       Useless::Doc::Rack::UI.new(base_app)

data/spec/useless/doc/rack/url_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + '/../../../spec_helper'
+
+require 'rack/test'
+require 'useless/doc/router'
+require 'useless/doc/rack/url'
+
+describe Useless::Doc::Rack::URL do
+  include Rack::Test::Methods
+
+  def app
+    @app ||= lambda do |env|
+      base_app = lambda do |env|
+        [200, {'Content-Type' => 'text/plain'}, [env['useless.doc.url']]]
+      end
+
+      env['useless.doc.router'] = Useless::Doc::Router.default
+      Useless::Doc::Rack::URL.new(base_app).call(env)
+    end
+  end
+
+  it 'should ask the router for the api URL' do
+    Useless::Doc::Router.default.should_receive(:api_for_doc).
+      with('http://some.doc.api.com/').and_return('http://some.api.com/')
+    get 'http://some.doc.api.com/'
+    last_response.should be_ok
+    last_response.body.should == 'http://some.api.com/'
+  end
+
+  it 'should return a 404 if the URL could not be determined' do
+    Useless::Doc::Router.default.should_receive(:api_for_doc).
+      with('http://some.doc.api.com/').and_return(nil)
+    get 'http://some.doc.api.com/'
+    last_response.should be_not_found
+  end
+end

data/spec/useless/doc/{rack/application_spec.rb → rack_spec.rb}

@@ -1,18 +1,19 @@
-require File.dirname(__FILE__) + '/../../../spec_helper'
+require File.dirname(__FILE__) + '/../../spec_helper'
 
 require 'rack/test'
-require 'useless/doc/rack/application'
-require 'useless/doc/rack/retriever'
+require 'useless/doc'
+require 'useless/doc/rack'
+require 'useless/doc/client'
 
-describe Useless::Doc::Rack::Application do
+describe Useless::Doc::Rack do
   include Rack::Test::Methods
 
   def app
-    @app ||= Useless::Doc::Rack::Application.new('some-api')
+    Useless::Doc::Rack.new
   end
 
   it 'should return a 404 if the JSON cannot be retrieved' do
-    Useless::Doc::Rack::Retriever::Stub.should_receive(:retrieve).
+    Useless::Doc::Client.stub.should_receive(:get).
       with('http://some-api.useless.io/some/non-existant/resource').
       and_return(nil)
 
@@ -25,20 +26,30 @@ describe Useless::Doc::Rack::Application do
     last_response.should be_not_found
   end
 
+  it 'should return domain HTML for the root path' do
+    Useless::Doc::Client.stub.should_receive(:get).
+      with('http://useless.io/').
+      and_return(Useless::Doc.load.domain(load_document('domain.json').read))
+
+    get 'http://doc.useless.io/'
+    last_response.should be_ok
+    last_response.body.should =~ /<h1>Useless<\/h1>/
+  end
+
   it 'should return API HTML if proper JSON is retrieved' do
-    Useless::Doc::Rack::Retriever::Stub.should_receive(:retrieve).
+    Useless::Doc::Client.stub.should_receive(:get).
       with('http://some-api.useless.io/').
-      and_return(load_document('api.json'))
+      and_return(Useless::Doc.load.api(load_document('api.json').read))
 
     get 'http://some-api.doc.useless.io/'
     last_response.should be_ok
-    last_response.body.should =~ /<h1>twonk\.useless\.io<\/h1>/
+    last_response.body.should =~ /<h1>Twonk API<\/h1>/
   end
 
   it 'should return resource HTML if proper JSON is retrieved' do
-    Useless::Doc::Rack::Retriever::Stub.should_receive(:retrieve).
+    Useless::Doc::Client.stub.should_receive(:get).
       with('http://some-api.useless.io/some/resource').
-      and_return(load_document('twonk.json'))
+      and_return(Useless::Doc.load.resource(load_document('twonk.json').read))
 
     get 'http://some-api.doc.useless.io/some/resource'
     last_response.should be_ok

data/spec/useless/doc/router_spec.rb

@@ -0,0 +1,38 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+require 'rack/test'
+require 'useless/doc'
+require 'useless/doc/router'
+
+describe Useless::Doc::Router::Default do
+  before(:all) do
+    @router = Useless::Doc::Router::Default.new('api.domain.com', 'useless.io')
+  end
+
+  describe '.doc_for_api' do
+    it 'should add a \'doc\' subdomain before the existing subdomain' do
+      @router.doc_for_api('http://api.domain.com/some/path').
+        should == 'http://api.doc.domain.com/some/path'
+    end
+
+    it 'should return nil if the specified URL is not part of the domain' do
+      @router.doc_for_api('http://nonexistant.domain.com/some/path').should be_nil
+    end
+  end
+
+  describe '.api_for_doc' do
+    it 'should remove the \'doc\' subdomain' do
+      @router.api_for_doc('http://api.doc.domain.com/some/path').
+        should == 'http://api.domain.com/some/path'
+    end
+
+    it 'should remove the \'doc\' subdomain, even if it\'s the only subdomain' do
+      @router.api_for_doc('http://doc.useless.io').
+        should == 'http://useless.io'
+    end
+
+    it 'should return nil if the resulting URL is not part of the domain' do
+      @router.api_for_doc('http://nonexistant.doc.domain.com/some/path').should be_nil
+    end
+  end
+end

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

@@ -2,6 +2,7 @@ require File.dirname(__FILE__) + '/../../../spec_helper'
 
 require 'useless/doc/core/api'
 require 'useless/doc/core/body'
+require 'useless/doc/core/domain'
 require 'useless/doc/core/header'
 require 'useless/doc/core/request'
 require 'useless/doc/core/resource'
@@ -22,6 +23,32 @@ describe Useless::Doc::Serialization::Dump do
     end
   end
 
+  describe '.domain' do
+    it 'should convert the specified Core::Domain instance to JSON' do
+      api = Useless::Doc::Core::API.new \
+        name: 'Twiddles API',
+        url: 'twiddles.useless.io',
+        description: 'Pretty much, like, everything you\'re looking for'
+
+      domain = Useless::Doc::Core::Domain.new \
+        name: 'Useless',
+        url: 'http://useless.io',
+        description: 'A collection of useless APIs.',
+        apis: [api]
+
+      json = Useless::Doc::Serialization::Dump.domain(domain)
+      hash = Useless::Doc::Serialization::Load.json_to_hash(json)
+      hash['name'].should == 'Useless'
+      hash['url'].should == 'http://useless.io'
+      hash['description'].should == 'A collection of useless APIs.'
+
+      api_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['apis'][0])
+      api_hash['name'].should == 'Twiddles API'
+      api_hash['url'].should == 'twiddles.useless.io'
+      api_hash['description'].should == 'Pretty much, like, everything you\'re looking for'
+    end
+  end
+
   describe '.api' do
     it 'should convert the specified Core::API instance to JSON' do
       resource = Useless::Doc::Core::Resource.new \
@@ -30,12 +57,14 @@ describe Useless::Doc::Serialization::Dump do
         requests:      []
 
       api = Useless::Doc::Core::API.new \
+        name: 'Twiddles API',
         url: 'twiddles.useless.io',
         description: 'Pretty much, like, everything you\'re looking for',
         resources: [resource]
 
       json = Useless::Doc::Serialization::Dump.api(api)
       hash = Useless::Doc::Serialization::Load.json_to_hash(json)
+      hash['name'].should == 'Twiddles API'
       hash['url'].should == 'twiddles.useless.io'
       hash['description'].should == 'Pretty much, like, everything you\'re looking for'
 

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

@@ -1,6 +1,9 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
 
 require 'useless/doc/serialization/load'
+require 'useless/doc/core/domain'
+require 'useless/doc/core/api'
+require 'useless/doc/core/resource'
 
 describe Useless::Doc::Serialization::Load do
   describe '.json_to_hash' do
@@ -16,10 +19,44 @@ describe Useless::Doc::Serialization::Load do
     end
   end
 
+  describe '.load' do
+    it 'should return a Domain instance if domain JSON is provided' do
+      document = load_document('domain.json')
+      api = Useless::Doc::Serialization::Load.load document.read
+      api.should be_an_instance_of(Useless::Doc::Core::Domain)
+    end
+
+    it 'should return an API instance if API JSON is provided' do
+      document = load_document('api.json')
+      api = Useless::Doc::Serialization::Load.load document.read
+      api.should be_an_instance_of(Useless::Doc::Core::API)
+    end
+
+    it 'should return a Resource instance if resource JSON is provided' do
+      document = load_document('twonk.json')
+      resource = Useless::Doc::Serialization::Load.load document.read
+      resource.should be_an_instance_of(Useless::Doc::Core::Resource)
+    end
+  end
+
+  describe '.domain' do
+    it 'should parse the specified JSON into a Domain instance' do
+      document = load_document('domain.json')
+      domain = Useless::Doc::Serialization::Load.domain document.read
+      domain.name.should == 'Useless'
+      domain.url.should == 'http://useless.io'
+      domain.description.should == 'A collection of useless APIs.'
+      domain.apis.first.name.should == 'The Jah API'
+      domain.apis.first.url.should == 'http://jah.useless.io'
+      domain.apis.first.description.should == 'Jah, jah, jah.'
+    end
+  end
+
   describe '.api' do
     it 'should parse the specified JSON into an API instance' do
       document = load_document('api.json')
       api = Useless::Doc::Serialization::Load.api document.read
+      api.name.should == 'Twonk API'
       api.url.should == 'twonk.useless.io'
       api.description.should == 'Twonk information. Duh.'
       api.resources.first.path.should == '/twonks/:id'

data/spec/useless/doc/sinatra_spec.rb

@@ -9,7 +9,8 @@ describe Useless::Doc::Sinatra do
   class DocApp < Sinatra::Base
     register Useless::Doc::Sinatra
 
-    doc 'resource.useless.io' do
+    doc 'Resoruce API' do
+      url 'resource.useless.io'
       description 'A resource repository'
       timestamp '2013-01-01 12:00 PM'
     end
@@ -69,6 +70,7 @@ describe Useless::Doc::Sinatra do
     options 'http://some-api.granmal.com/'
     api = Useless::Doc::Serialization::Load.api(last_response.body)
 
+    api.name.should == 'Resoruce API'
     paths = api.resources.map { |resource| resource.path }
     paths.length.should == 2
     paths.should include '/some-resources'