useless-doc 0.2.0 → 0.2.1

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

@@ -0,0 +1,27 @@
+module Useless
+  module Doc
+    module Core
+
+      # Documentation for an entire API.
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the API.
+      #
+      # @!attribute [r] resources
+      #   @return [Array<Resource>] the resources included in the API.
+      #
+      class API
+
+        attr_accessor :url, :description, :resources
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @url = attrs[:url]
+          @description = attrs[:description]
+          @resources = attrs[:resources]
+        end
+      end
+    end
+  end
+end

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

@@ -38,7 +38,7 @@ module Useless
 
           request = ::Rack::Request.new(env)
 
-          if true or valid_subdomain?(request.url)
+          if valid_subdomain?(request.url)
             url = Proxy.transform_url(request.url)
 
             if json = env['useless.doc.retriever'].retrieve(url)

data/lib/useless/doc/serialization/dump.rb

@@ -18,9 +18,24 @@ module Useless
           hash.is_a?(String) ? hash : Oj.dump(hash)
         end
 
-        # Converts +Doc::Resource+ instance to a JSON representation.
+        # Converts +Core::API+ instance to a JSON representation.
         #
-        # @param [Doc::Resource] resource the resource to be converted to JSON.
+        # @param [Core::API] api the API to be converted to JSON.
+        #
+        # @return [String] a JSON representation of the specified API.
+        #
+        def self.api(api)
+          if api
+            hash_to_json \
+              'url' => api.url,
+              'description' => api.description,
+              'resources' => api.resources.map { |resource| resource(resource) }
+          end
+        end
+
+        # Converts a +Core::Resource+ instance to a JSON representation.
+        #
+        # @param [Core::Resource] resource the resource to be converted to JSON.
         #
         # @return [String] a JSON representation of the specified resource.
         #

data/lib/useless/doc/serialization/load.rb

@@ -1,5 +1,6 @@
 require 'oj'
 
+require 'useless/doc/core/api'
 require 'useless/doc/core/body'
 require 'useless/doc/core/header'
 require 'useless/doc/core/request'
@@ -23,12 +24,33 @@ module Useless
           json.is_a?(Hash) ? json : Oj.load(json)
         end
 
-        # Converts a JSON represntation to an instance of +Doc::Resource+
+        # Converts a JSON represntation to an instance of +Core::API+
+        #
+        # @param [String, Hash] json the JSON representation to be converted to
+        #   an API.
+        #
+        # @return [Core::API] the API corresponding to the specified
+        #   JSON.
+        #
+        def self.api(json)
+          hash = json_to_hash json
+
+          resources = (hash['resources'] || []).map do |json|
+            resource json
+          end
+
+          Useless::Doc::Core::API.new \
+            url:          hash['url'],
+            description:  hash['description'],
+            resources:    resources
+        end
+
+        # Converts a JSON represntation to an instance of +Core::Resource+
         #
         # @param [String, Hash] json the JSON representation to be converted to
         #   a resource.
         #
-        # @return [Doc::Resource] the resource corresponding to the specified
+        # @return [Core::Resource] the resource corresponding to the specified
         #   JSON.
         #
         def self.resource(json)

data/lib/useless/doc/version.rb

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

data/spec/documents/api.json

@@ -0,0 +1,11 @@
+{
+  "url": "twonk.useless.io",
+  "description": "Twonk information. Duh.",
+  "resources": [
+    {
+      "path": "/twonks/:id",
+      "description": "The most critical aspect.",
+      "requests": []
+    }
+  ]
+}

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

@@ -1,5 +1,6 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
 
+require 'useless/doc/core/api'
 require 'useless/doc/core/body'
 require 'useless/doc/core/header'
 require 'useless/doc/core/request'
@@ -21,8 +22,31 @@ describe Useless::Doc::Serialization::Dump do
     end
   end
 
+  describe '.api' do
+    it 'should convert the specified Core::API instance to JSON' do
+      resource = Useless::Doc::Core::Resource.new \
+        path:         '/twiddles',
+        description:  'The full lot of twiddles.',
+        requests:      []
+
+      api = Useless::Doc::Core::API.new \
+        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['url'].should == 'twiddles.useless.io'
+      hash['description'].should == 'Pretty much, like, everything you\'re looking for'
+
+      resource_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['resources'][0])
+      resource_hash['path'].should == '/twiddles'
+      resource_hash['description'].should == 'The full lot of twiddles.'
+    end
+  end
+
   describe '.resource' do
-    it 'should convert the specified Doc::Resource instance into JSON' do
+    it 'should convert the specified Core::Resource instance into JSON' do
       get_response_header = Useless::Doc::Core::Header.new \
         key:          'Type',
         description:  'The response type.'

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

@@ -16,6 +16,17 @@ describe Useless::Doc::Serialization::Load do
     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.url.should == 'twonk.useless.io'
+      api.description.should == 'Twonk information. Duh.'
+      api.resources.first.path.should == '/twonks/:id'
+      api.resources.first.description.should == 'The most critical aspect.'
+    end
+  end
+
   describe '.resource' do
     it 'should parse the specified JSON into a model hierarchy' do
       document = load_document('twonk.json')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-08 00:00:00.000000000 Z
+date: 2013-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -152,6 +152,7 @@ files:
 - README.md
 - Rakefile
 - lib/useless/doc.rb
+- lib/useless/doc/core/api.rb
 - lib/useless/doc/core/body.rb
 - lib/useless/doc/core/header.rb
 - lib/useless/doc/core/request.rb
@@ -172,6 +173,7 @@ files:
 - lib/useless/doc/ui/godel/stylesheet.css
 - lib/useless/doc/ui/godel/template.mustache
 - lib/useless/doc/version.rb
+- spec/documents/api.json
 - spec/documents/twonk.json
 - spec/spec_helper.rb
 - spec/useless/doc/dsl_spec.rb
@@ -210,6 +212,7 @@ signing_key:
 specification_version: 3
 summary: For parsing and serving Useless documentation.
 test_files:
+- spec/documents/api.json
 - spec/documents/twonk.json
 - spec/spec_helper.rb
 - spec/useless/doc/dsl_spec.rb