useless-doc 0.2.1 → 0.2.2

data/lib/useless/doc/core/api.rb

@@ -4,21 +4,28 @@ module Useless
 
       # Documentation for an entire API.
       #
+      # @!attribute [r] url
+      #   @return [String] a the URL of the API.
+      #
       # @!attribute [r] description
       #   @return [String] a description of the API.
       #
+      # @!attribute [r] timestamp
+      #   @return [Time] the time that this API doc was last updated.
+      #
       # @!attribute [r] resources
       #   @return [Array<Resource>] the resources included in the API.
       #
       class API
 
-        attr_accessor :url, :description, :resources
+        attr_accessor :url, :description, :timestamp, :resources
 
         # @param [Hash] attrs corresponds to the class's instance attributes.
         #
         def initialize(attrs = {})
           @url = attrs[:url]
           @description = attrs[:description]
+          @timestamp = attrs[:timestamp]
           @resources = attrs[:resources]
         end
       end

data/lib/useless/doc/dsl.rb

@@ -1,3 +1,4 @@
+require 'useless/doc/core/api'
 require 'useless/doc/core/body'
 require 'useless/doc/core/header'
 require 'useless/doc/core/request'
@@ -7,14 +8,14 @@ require 'useless/doc/core/response'
 module Useless
   module Doc
 
-    # A simple DSL for building resource documentation.
+    # A simple DSL for building API documentation.
     #
     # @example
-    #   Useless::Doc::DSL::Resource.build do
-    #     path '/resources'
-    #     description 'The entire collection of resources.'
+    #   Useless::Doc.api 'resource.useless.io' do
+    #     description 'A source of resources'
     #
-    #     get 'Returns a full listing of the resources.' do
+    #     get '/resources' do
+    #       description 'Returns a full listing of the resources.'
     #       authentication_required false
     #       parameter 'page', 'The page of resources to be returned.'
     #       header 'X-Twiddle', 'The twiddle threshold.'
@@ -42,7 +43,10 @@ module Useless
         end
 
         def self.included(base)
-          base.send(:extend, ClassMethods)
+          base.instance_eval do
+            extend ClassMethods
+            attr_reader :attributes
+          end
         end
 
         def initialize(attributes = {})
@@ -60,6 +64,89 @@ module Useless
         end
       end
 
+      class API
+        include DSL::Member
+
+        def initialize(attributes = {})
+          @resource_dsls = []
+          super
+        end
+
+        def default_attributes
+          { resources: [] }
+        end
+
+        def generate
+          @attributes[:resources] = @resource_dsls.map do |resource_dsl|
+            resource_dsl.generate
+          end
+
+          super
+        end
+
+        def url(url)
+          @attributes[:url] = url
+        end
+
+        def description(description)
+          @attributes[:description] = description
+        end
+
+        def timestamp(timestamp)
+          if timestamp.is_a?(String)
+            timestamp = Time.parse(timestamp)
+          end
+
+          @attributes[:timestamp] = timestamp
+        end
+
+        def get(path, &block)
+          resource(path).get(&block)
+        end
+
+        def head(path, &block)
+          resource(path).head(&block)
+        end
+
+        def post(path, &block)
+          resource(path).post(&block)
+        end
+
+        def put(path, &block)
+          resource(path).put(&block)
+        end
+
+        def patch(path, &block)
+          resource(path).patch(&block)
+        end
+
+        def delete(path, &block)
+          resource(path).delete(&block)
+        end
+
+        def trace(path, &block)
+          resource(path).trace(&block)
+        end
+
+        def connect(path, &block)
+          resource(path).connect(&block)
+        end
+
+        def resource(path, &block)
+          resource_dsl = @resource_dsls.find do |resource|
+            resource.attributes[:path] == path
+          end
+
+          unless resource_dsl
+            resource_dsl = Resource.new(path: path)
+            @resource_dsls << resource_dsl
+          end
+
+          resource_dsl.instance_eval(&block) if block_given?
+          resource_dsl
+        end
+      end
+
       class Resource
         include DSL::Member
 
@@ -107,8 +194,6 @@ module Useless
           method(Doc::Core::Request::Method::CONNECT, description, &block)
         end
 
-        private
-
         def method(type, description, &block)
           attributes = { method: type, description: description }
           @attributes[:requests] << Request.build(attributes, &block)

data/lib/useless/doc/rack/retriever.rb

@@ -1,3 +1,4 @@
+require 'time'
 require 'typhoeus'
 
 module Useless
@@ -25,9 +26,32 @@ module Useless
         end
 
         module Standard
+          NotModified = 304
+
+          @cache = {}
+
           def self.retrieve(url)
-            response = Typhoeus.options url, headers: { 'Accept' => 'application/json' }
-            response.response_body
+            headers = { 'Accept' => 'application/json' }
+
+            if @cache[url]
+              headers['If-Modified-Since'] = @cache[url].timestamp.httpdate()
+            end
+
+            response = Typhoeus.options url, headers: headers
+
+            unless response.response_code == NotModified
+              @cache[url] = CacheItem.new(response.response_body, Time.now)
+            end
+
+            @cache[url].response_body
+          end
+
+          class CacheItem
+            attr_accessor :response_body, :timestamp
+
+            def initialize(response_body, timestamp)
+              @response_body, @timestamp = response_body, timestamp
+            end
           end
         end
 

data/lib/useless/doc/sinatra.rb

@@ -5,40 +5,74 @@ require 'useless/doc/serialization/dump'
 
 module Useless
   module Doc
+
+    # Provides access to the +Doc::DSL+ via the +.doc+ method. The JSON of the
+    # API doc that is built will be served via an OPTIONS request to the root.
+    # Resource documentation is similarly served via an OPTIONS request to the
+    # corresponding path.
+    #
+    # @example
+    #   class ResourceApp < Sinatra::Base
+    #     register Useless::Doc::Sinatra
+    #
+    #     doc 'resources.useless.io' do
+    #       description 'A place with resources'
+    #     end
+    #
+    #     doc.get '/some-resources' do
+    #       description 'Get all of these resources'
+    #
+    #       request do
+    #         parameter 'page', 'The page of resources to return.'
+    #       end
+    #
+    #       response do
+    #         body do
+    #           attribute 'name', 'The name of the resource.'
+    #         end
+    #       end
+    #     end
+    #
+    #     ...
+    #
+    #   end
+    #
     module Sinatra
+      def doc=(doc)
+        @doc = doc
+      end
+
+      def doc(url = nil, &block)
+        @dsl ||= Useless::Doc::DSL::API.new(url: url)
+        @dsl.instance_eval(&block) if block_given?
+        @dsl
+      end
+
+      def generated_doc
+        @doc ||= @dsl.generate if @dsl
+      end
+
+      def self.registered(app)
+        app.options '/' do
+          if api = self.class.generated_doc
+            last_modified api.timestamp
+            Useless::Doc::Serialization::Dump.api(api)
+          end
+        end
+
+        app.options '/*' do
+          if api = self.class.generated_doc
+            resource = api.resources.find do |resource|
+              resource.path == "/#{params[:splat].first}"
+            end
+
+            if resource
+              last_modified api.timestamp
+              return Useless::Doc::Serialization::Dump.resource(resource)
+            end
+          end
 
-      # Provides access to the +Doc::DSL+. The JSON of the resource that is
-      # created will then be served via an OPTIONS request to the specified
-      # +path+.
-      #
-      # @param [String] path the path of the resource to be documented.
-      #
-      # @param block is passed to the DSL to build the resource.
-      #
-      # @example
-      #   class ResourceApp < Sinatra::Base
-      #     register Useless::Doc::Sinatra
-      # 
-      #     doc '/some-resources' do
-      #       get 'Get all of these resources' do
-      #         request do
-      #           parameter 'page', 'The page of resources to return.'
-      #         end
-      #
-      #         response do
-      #           body do
-      #             attribute 'name', 'The name of the resource.'
-      #           end
-      #         end
-      #       end
-      #     end
-      #   end
-      #
-      def doc(path, &block)
-        resource = Useless::Doc::DSL::Resource.build path: path, &block
-
-        options(path) do
-          Doc::Serialization::Dump.resource(resource)
+          pass
         end
       end
     end

data/lib/useless/doc/version.rb

@@ -1,5 +1,5 @@
 module Useless
   module Doc
-    VERSION = '0.2.1'
+    VERSION = '0.2.2'
   end
 end

data/lib/useless/doc.rb

@@ -1,4 +1,9 @@
+require 'useless/doc/dsl'
+
 module Useless
   module Doc
+    def self.api(url, &block)
+      DSL::API.build url: url, &block
+    end
   end
 end

data/spec/useless/doc/dsl_spec.rb

@@ -1,17 +1,22 @@
 require File.dirname(__FILE__) + '/../../spec_helper'
 
+require 'time'
 require 'rack/test'
+require 'useless/doc'
 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'
+    it 'should provide a terse DSL for building API documentation (through Useless::Doc.api)' do
+      api = Useless::Doc.api 'widget.useless.io' do
+        description 'The canonical source of worldwide widgets.'
 
-        get 'Returns a full listing of the collection' do
+        resource('/widgets').description 'The whole kit and kaboodle.'
+
+        get '/widgets' do
+          description 'List the entire collection of widgets.'
           authentication_required false
+
           parameter 'page', 'The page of widgets that you\'d like', 
             type: :query, required: false, default: 1
           header 'X-Twiddle', 'The twiddle threshold.'
@@ -30,7 +35,7 @@ describe Useless::Doc::DSL do
           end
         end
 
-        post do
+        post '/widgets' do
           authentication_required true
           description 'Creates a new widget'
 
@@ -44,17 +49,42 @@ describe Useless::Doc::DSL do
           response 201, 'The widget was successfully created'
           response 422, 'The widget couldn\'t be created because name was missing'
         end
+
+        delete '/widgets/:id' do
+          response 404, 'The widget could not be found.'
+          response 200, 'The widgets was deleted successfully'
+        end
+
+        resource '/widgets/:id' do
+          put do
+            description 'Resource-oriented specification.'
+          end
+        end
+
+        timestamp '2013-01-12 12:44 AM'
       end
 
-      resource.description.should == 'The entire collection of widgets'
-      resource.requests[0].method.should == 'GET'
-      resource.requests[0].headers[0].description.should == 'The twiddle threshold.'
-      resource.requests[0].responses[1].code.should == 200
-      resource.requests[1].method.should == 'POST'
-      resource.requests[1].description.should == 'Creates a new widget'
-      resource.requests[1].body.content_type.should == 'application/json'
-      resource.requests[1].body.attributes[0].key.should == 'name'
-      resource.requests[1].responses[1].description.should == 'The widget couldn\'t be created because name was missing'
+      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')
+
+      collection = api.resources.find { |resource| resource.path == '/widgets' }
+      collection.description.should == 'The whole kit and kaboodle.'
+      collection.requests[0].method.should == 'GET'
+      collection.requests[0].headers[0].description.should == 'The twiddle threshold.'
+      collection.requests[0].responses[1].code.should == 200
+      collection.requests[1].method.should == 'POST'
+      collection.requests[1].description.should == 'Creates a new widget'
+      collection.requests[1].body.content_type.should == 'application/json'
+      collection.requests[1].body.attributes[0].key.should == 'name'
+      collection.requests[1].responses[1].description.should == 'The widget couldn\'t be created because name was missing'
+
+      instance = api.resources.find { |resource| resource.path == '/widgets/:id' }
+      instance.requests[0].method.should == 'DELETE'
+      instance.requests[0].responses[0].code.should == 404
+      instance.requests[0].responses[1].code.should == 200
+      instance.requests[1].method.should == 'PUT'
+      instance.requests[1].description.should == 'Resource-oriented specification.'
     end
   end
 end

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

@@ -1,5 +1,6 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
 
+require 'time'
 require 'rack/test'
 require 'useless/doc/rack/retriever'
 
@@ -42,8 +43,34 @@ describe Useless::Doc::Rack::Retriever do
   end
 
   describe Useless::Doc::Rack::Retriever::Standard do
-    it 'should respond to `retrieve`' do
-      Useless::Doc::Rack::Retriever::Standard.should respond_to(:retrieve)
+    before(:each) do
+      Useless::Doc::Rack::Retriever::Standard.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: '{ "some": "json" }'))
+
+      response = Useless::Doc::Rack::Retriever::Standard.retrieve('http://some-api.granmal.com/some/resource')
+      response.should == '{ "some": "json" }'
+    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: '{ "some": "json" }'))
+
+      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: ''))
+
+      Useless::Doc::Rack::Retriever::Standard.retrieve('http://some-api.granmal.com/some/resource')
+      response = Useless::Doc::Rack::Retriever::Standard.retrieve('http://some-api.granmal.com/some/resource')
+      response.should == '{ "some": "json" }'
     end
   end
 

data/spec/useless/doc/sinatra_spec.rb

@@ -9,23 +9,20 @@ describe Useless::Doc::Sinatra do
   class DocApp < Sinatra::Base
     register Useless::Doc::Sinatra
 
-    doc '/some-resources' do
-      get 'Get all of these resources' do
-        parameter 'since', 'Only resources after this date.'
-
-        response 200, 'The responses were fetched correctly.' do
-          body do
-            attribute 'name', 'The name of the resource.'
-          end
-        end
-      end
+    doc 'resource.useless.io' do
+      description 'A resource repository'
+      timestamp '2013-01-01 12:00 PM'
+    end
+
+    doc.get '/some-resources' do
+      description 'Get all of these resources'
 
-      post 'Make a new resource' do
+      parameter 'since', 'Only resources after this date.'
+
+      response 200, 'The responses were fetched correctly.' do
         body do
           attribute 'name', 'The name of the resource.'
         end
-
-        response 201, 'The resource was successfully created.'
       end
     end
 
@@ -33,9 +30,33 @@ describe Useless::Doc::Sinatra do
       []
     end
 
+    doc.post '/some-resources' do
+      description 'Make a new resource'
+
+      body do
+        attribute 'name', 'The name of the resource.'
+      end
+
+      response 201, 'The resource was successfully created.'
+    end
+
     post '/some-resources' do
       201
     end
+
+    doc.put '/some-resources/:id' do
+      description 'Update a resource'
+
+      body do
+        attribute 'name', 'The name of the resource.'
+      end
+
+      response 200, 'The resource was successfully updated.'
+    end
+
+    put '/some-resources/:id' do
+      200
+    end
   end
 
   include Rack::Test::Methods
@@ -44,7 +65,17 @@ describe Useless::Doc::Sinatra do
     DocApp
   end
 
-  it 'should serve documentation for the documented resource' do
+  it 'should serve documentation for the whole API from root.' do
+    options 'http://some-api.granmal.com/'
+    api = Useless::Doc::Serialization::Load.api(last_response.body)
+
+    paths = api.resources.map { |resource| resource.path }
+    paths.length.should == 2
+    paths.should include '/some-resources'
+    paths.should include '/some-resources/:id'
+  end
+
+  it 'should serve documentation for the specified resource.' do
     options 'http://some-api.granmal.com/some-resources'
     resource = Useless::Doc::Serialization::Load.resource(last_response.body)
 
@@ -57,4 +88,24 @@ describe Useless::Doc::Sinatra do
     post.responses[0].code.should == 201
   end
 
+  it 'should return a 404 if the specified resource doesn\'t exist' do
+    options 'http://some-api.granmal.com/some-nonexistant-resources'
+    last_response.should be_not_found
+  end
+
+  it 'should return a 304 if the doc has not been modified since specified time' do
+    header 'If-Modified-Since', Time.parse('2013-01-02 12:00 PM').httpdate
+    options 'http://some-api.granmal.com/'
+    last_response.status.should == 304
+    options 'http://some-api.granmal.com/some-resources'
+    last_response.status.should == 304
+  end
+
+  it 'should not return a 304 if the doc has been modified since the specified time' do
+    header 'If-Modified-Since', Time.parse('2012-12-31 12:00 PM').httpdate
+    options 'http://some-api.granmal.com/'
+    last_response.status.should_not == 304
+    options 'http://some-api.granmal.com/some-resources'
+    last_response.status.should_not == 304
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-09 00:00:00.000000000 Z
+date: 2013-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj