useless-doc 0.1.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+/doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+log

data/.rbenv-version

@@ -0,0 +1 @@
+1.9.3-p327

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in useless-doc.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Kevin Hyland
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,3 @@
+# Useless::Doc
+
+For parsing and serving Useless documentation.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/config.ru

@@ -0,0 +1,4 @@
+$:.push File.dirname(__FILE__) + '/lib'
+require 'useless/doc/rack/application'
+
+run Useless::Doc::Rack::Application

data/lib/useless/doc/action.rb

@@ -0,0 +1,50 @@
+module Useless
+  module Doc
+
+    # Documentation for an action on a API resource.
+    #
+    # @!attribute [r] description
+    #   @return [String] a description of the action.
+    #
+    # @!attribute [r] method
+    #   @return [String] the action's HTTP method.
+    #   @see Useless::Doc::Action::Method
+    #
+    # @!attribute [r] authentication_required
+    #   @return [Boolean] whether or not the user needs to authenticate in
+    #     order to perform this action.
+    #
+    # @!attribute [r] request
+    #   @return [Request] the request documentation for the action.
+    #
+    # @!attribute [r] response
+    #   @return [Response] the response documentation for the action.
+    #
+    class Action
+
+      module Method
+        GET     = 'GET'
+        HEAD    = 'HEAD'
+        POST    = 'POST'
+        PUT     = 'PUT'
+        PATCH   = 'PATCH'
+        DELETE  = 'DELETE'
+        TRACE   = 'TRACE'
+        CONNECT = 'CONNECT'
+      end
+
+      attr_reader :description, :method, :authentication_required,
+        :request, :response
+
+      # @param [Hash] attrs corresponds to the class's instance attributes.
+      #
+      def initialize(attrs = {})
+        @description              = attrs[:description]
+        @method                   = attrs[:method]
+        @authentication_required  = attrs[:authentication_required]
+        @request                  = attrs[:request]
+        @response                 = attrs[:response]
+      end
+    end
+  end
+end

data/lib/useless/doc/body.rb

@@ -0,0 +1,58 @@
+module Useless
+  module Doc
+
+    # Documentation for an HTTP body, belonging either to the request or the
+    # response.
+    #
+    # @!attribute [r] content_type
+    #   @return [String] the MIME type of the body.
+    #
+    # @!attribute [r] attributes
+    #   @return [Array<Body::Attribute>] documentation for each of the body
+    #     attributes.
+    #
+    class Body
+
+      attr_reader :content_type, :attributes
+
+      # @param [Hash] attrs corresponds to the class's instance attributes.
+      #
+      def initialize(attrs)
+        @content_type = attrs[:content_type]
+        @attributes   = attrs[:attributes]
+      end
+
+      # Documentation for an attribute on an HTTP body.
+      #
+      # @!attribute [r] key
+      #   @return [String] the key of this attribute in the body.
+      #
+      # @!attribute [r] value_type
+      #   @return [String] one of "string", "number", "object",
+      #     "array", or "boolean". "string" is the default value.
+      #
+      # @!attribute [r] required
+      #   @return [Boolean] whether or not the attribute is required. If it
+      #     is required, and the attribute is omitted, the response should have
+      #     a 4xx code. +true+ is the default value.
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the attribute.
+      #
+      class Attribute
+
+        attr_reader :key, :type, :required, :default, :description
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs)
+          @key          = attrs[:key]
+          @type         = attrs[:type] || 'string'
+          @required     = attrs.key?(:required) ? attrs[:required] : true
+          @default      = attrs[:default]
+          @description  = attrs[:description]
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/dsl.rb

@@ -0,0 +1,208 @@
+require 'useless/doc/action'
+require 'useless/doc/body'
+require 'useless/doc/header'
+require 'useless/doc/request'
+require 'useless/doc/request/parameter'
+require 'useless/doc/resource'
+require 'useless/doc/response'
+require 'useless/doc/response/status'
+
+module Useless
+  module Doc
+
+    # A simple DSL for building resource documentation.
+    #
+    # @example
+    #   Useless::Doc::DSL::Resource.build do
+    #     path '/resources'
+    #     description 'The entire collection of resources.'
+    #
+    #     get 'Returns a full listing of the resources.' do
+    #       authentication_required false
+    #
+    #       request do
+    #         parameter 'page', 'The page of resources to be returned.'
+    #         header 'X-Twiddle', 'The twiddle threshold.'
+    #       end
+    #
+    #       response do
+    #         status 200, 'The resources were returned successfully.'
+    #
+    #         header 'X-Twonk', 'The twonk coefficient.'
+    #
+    #         body do
+    #           content_type 'application/json'
+    #           attribute 'name', 'The name of the resource.', required: true
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    class DSL
+
+      module Member
+        module ClassMethods
+          def build(attributes = {}, &block)
+            resource = new(attributes)
+            resource.instance_eval(&block)
+            resource.generate
+          end
+        end
+
+        def self.included(base)
+          base.send(:extend, ClassMethods)
+        end
+
+        def initialize(attributes = {})
+          @attributes = default_attributes.merge(attributes)
+        end
+
+        def generate
+          name = self.class.name.split('::').last
+          klass = eval("Doc::#{name}")
+          klass.new(@attributes)
+        end
+
+        def default_attributes
+          {}
+        end
+      end
+
+      class Resource
+        include DSL::Member
+
+        def default_attributes
+          { actions: [] }
+        end
+
+        def path(path)
+          @attributes[:path] = path
+        end
+
+        def description(description)
+          @attributes[:description] = description
+        end
+
+        def get(description = nil, &block)
+          method(Doc::Action::Method::GET, description, &block)
+        end
+
+        def head(description = nil, &block)
+          method(Doc::Action::Method::HEAD, description, &block)
+        end
+
+        def post(description = nil, &block)
+          method(Doc::Action::Method::POST, description, &block)
+        end
+
+        def put(description = nil, &block)
+          method(Doc::Action::Method::PUT, description, &block)
+        end
+
+        def patch(description = nil, &block)
+          method(Doc::Action::Method::PATCH, description, &block)
+        end
+
+        def delete(description = nil, &block)
+          method(Doc::Action::Method::DELETE, description, &block)
+        end
+
+        def trace(description = nil, &block)
+          method(Doc::Action::Method::TRACE, description, &block)
+        end
+
+        def connect(description = nil, &block)
+          method(Doc::Action::Method::CONNECT, description, &block)
+        end
+
+        private
+
+        def method(type, description, &block)
+          attributes = { method: type, description: description }
+          @attributes[:actions] << Action.build(attributes, &block)
+        end
+      end
+
+      class Action
+        include DSL::Member
+
+        def description(description)
+          @attributes[:description] = description
+        end
+
+        def authentication_required(value = nil)
+          @attributes[:authentication_required] = value.nil? ? true : value
+        end
+
+        def request(&block)
+          @attributes[:request] = Request.build({}, &block)
+        end
+
+        def response(&block)
+          @attributes[:response] = Response.build({}, &block)
+        end
+      end
+
+      class Request
+        include DSL::Member
+
+        def default_attributes
+          { parameters: [], headers: [] }
+        end
+
+        def parameter(key, description, attributes = {})
+          parameter = Doc::Request::Parameter.new attributes.merge(key: key, description: description)
+          @attributes[:parameters] << parameter
+        end
+
+        def header(key, description)
+          header = Doc::Header.new key: key, description: description
+          @attributes[:headers] << header
+        end
+
+        def body(&block)
+          @attributes[:body] = Body.build({}, &block)
+        end
+      end
+
+      class Response
+        include DSL::Member
+
+        def default_attributes
+          { statuses: [], headers: [] }
+        end
+
+        def status(code, description)
+          status = Doc::Response::Status.new code: code, description: description
+          @attributes[:statuses] << status
+        end
+
+        def header(key, description)
+          header = Doc::Header.new key: key, description: description
+          @attributes[:headers] << header
+        end
+
+        def body(&block)
+          @attributes[:body] = Body.build({}, &block)
+        end
+      end
+
+      class Body
+        include DSL::Member
+
+        def default_attributes
+          { attributes: [] }
+        end
+
+        def content_type(value)
+          @attributes[:content_type] = value
+        end
+
+        def attribute(key, description, attributes = {})
+          attribute = Doc::Body::Attribute.new attributes.merge(key: key, description: description)
+          @attributes[:attributes] << attribute
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/header.rb

@@ -0,0 +1,24 @@
+module Useless
+  module Doc
+
+    # Documentation for an HTTP header, belonging either to the request or the
+    # response.
+    #
+    # @!attribute [r] key
+    #   @return [String] the key of the header.
+    #
+    # @!attribute [r] description
+    #   @return [String] a description of the header.
+    #
+    class Header
+      attr_accessor :key, :description
+
+      # @param [Hash] attrs corresponds to the class's instance attributes.
+      #
+      def initialize(attrs = {})
+        @key          = attrs[:key]
+        @description  = attrs[:description]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+require 'rack/builder'
+require 'rack/commonlogger'
+require 'rack/reloader'
+require 'low/rack/rack_errors'
+require 'low/rack/request_logger'
+
+require 'useless/doc/rack/proxy'
+require 'useless/doc/rack/stylesheet'
+require 'useless/doc/rack/transform'
+require 'useless/doc/rack/ui'
+
+module Useless
+  module Doc
+    module Rack
+      module Application
+        def self.call(env)
+          ::Rack::Builder.app do
+            use Low::Rack::RackErrors
+            use Low::Rack::RequestLogger
+            use ::Rack::CommonLogger
+            use Useless::Doc::Rack::UI
+            use Useless::Doc::Rack::Stylesheet
+            use Useless::Doc::Rack::Transform
+
+            run Useless::Doc::Rack::Proxy.new
+          end.call(env)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+require 'uri'
+require 'typhoeus'
+require 'rack/request'
+
+module Useless
+  module Doc
+    module Rack
+
+      # +Doc::Proxy+ is a Rack app that provides an HTML interface to Useless
+      # API documentation. It assumes that each API resource responds to INFO
+      # requests with documentation JSON that corresponds to the format
+      # specified by +Doc::Serialization::Load+.
+      #
+      # It proxies requests according to a simple convention. For example, a
+      # GET request to some-api.doc.useless.io/some/resource will result in an
+      # OPTIONS request to some-api.useless.io/some/resource.
+      #
+      # If there is no corresponding endpoint, the proxy will respond with a
+      # 404.
+      #
+      class Proxy
+
+        def self.transform_url(url)
+          uri = URI(url)
+          new_host = uri.host.gsub(/\.doc\./, '.')
+          "#{uri.scheme}://#{new_host}#{uri.path}"
+        end
+
+        def call(env)
+          request = ::Rack::Request.new(env)
+          url = Proxy.transform_url(request.url)
+
+          if json = retrieve_resource(url)
+            [200, {'Content-Type' => 'application/json'}, [json]]
+          else
+            [404, {'Content-Type' => 'text/plain'}, ['Documentation JSON is missing.']]
+          end
+        end
+
+        def retrieve_resource(url)
+          response = Typhoeus.options url, headers: { 'Accept' => 'application/json' }
+          response.response_body
+        end
+
+        # +Proxy::Stub+ retrieves JSON from the spec/documents directory for
+        # easy UI testing.
+        #
+        class Stub < Proxy
+          def retrieve_resource(url)
+            uri = URI(url)
+            path = File.dirname(__FILE__) + "/../../../../spec/documents#{uri.path}.json"
+            File.read(path)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+module Useless
+  module Doc
+    module Rack
+
+      # +Doc::Rack::Stylesheet+ serves the stylesheet for the current +Doc::UI+
+      # iff the request path is '/doc.css'. Otherwise, it passes the request
+      # through.
+      # 
+      class Stylesheet
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          if env["PATH_INFO"].to_s == '/doc.css'
+            [200, {'Content-Type' => 'text/css'}, [env['useless.doc.ui'].css]]
+          else
+            @app.call(env)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+require 'useless/doc/serialization/load'
+
+module Useless
+  module Doc
+    module Rack
+
+      # +Doc::Rack::Transform+ takes the a JSON response and attempts to parse
+      # it via +Doc::Serialization::Load+ and render it as HTML via the UI
+      # specified by env['useless.doc.ui'].
+      #
+      # If the JSON cannot be parsed, the response will be a 502.
+      #
+      class Transform
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          response = @app.call(env)
+
+          if response[0] == 200 and response[1]['Content-Type'] == 'application/json'
+            begin
+              resource = Serialization::Load.resource(response[2].first)
+              [200, {'Content-Type' => 'text/html'}, [env['useless.doc.ui'].html(resource)]]
+            rescue Oj::ParseError
+              [502, {'Content-Type' => 'text/plain'}, ['Documentation JSON is malformed.']]
+            end
+          else
+            response
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+require 'rack/request'
+require 'useless/doc/ui/godel'
+
+module Useless
+  module Doc
+    module Rack
+
+      # +Doc::Rack::UI+ chooses which UI should be used to render the
+      # documentation. It can theoretically be chosen via the 'ui' parameter,
+      # but for now it will alway choose +Godel+
+      #
+      class UI
+        def self.default
+          Useless::Doc::UI::Godel
+        end
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          request = ::Rack::Request.new(env)
+
+          ui = case request.params['ui']
+          when 'godel' then Useless::Doc::UI::Godel
+          else              Rack::UI.default
+          end
+
+          env['useless.doc.ui'] = ui
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/request/parameter.rb

@@ -0,0 +1,47 @@
+module Useless
+  module Doc
+    class Request
+
+      # Documentation for a request parameter for an API action.
+      #
+      # @!attribute [r] type
+      #   @return [String] either "path" if it's part of the URL path, or
+      #     "query" if it's part of the query string.
+      #
+      # @!attribute [r] key
+      #   @return [String] the key of the parameter.
+      #
+      # @!attribute [r] required
+      #   @return [Boolean] whether or not the parameter is required. If it is
+      #     required, and the attribute is omitted, the response should have a
+      #     4xx code.
+      #
+      # @!attribute [r] default
+      #   @return [String, Numeric] the value used if the parameter is omitted
+      #     and is not required.
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the parameter.
+      #
+      class Parameter
+
+        module Type
+          PATH = 'path'
+          QUERY = 'query'
+        end
+
+        attr_reader :type, :key, :required, :default, :description
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @type         = attrs[:type]
+          @key          = attrs[:key]
+          @required     = attrs[:required]
+          @default      = attrs[:default]
+          @description  = attrs[:description]
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/request.rb

@@ -0,0 +1,29 @@
+module Useless
+  module Doc
+
+    # Documentation for an HTTP request.
+    #
+    # @!attribute [r] parameters
+    #   @return [Array<Request::Parameter] documentation for the parameters
+    #     of the request.
+    #
+    # @!attribute [r] headers
+    #   @return [Array<Header>] documentation for the headers of the
+    #     request.
+    #
+    # @!attribute [r] body
+    #   @return [Body] documentation for the body of the request.
+    #
+    class Request
+      attr_accessor :parameters, :headers, :body
+
+      # @param [Hash] attrs corresponds to the class's instance attributes.
+      #
+      def initialize(attrs = {})
+        @parameters = attrs[:parameters]
+        @headers    = attrs[:headers]
+        @body       = attrs[:body]
+      end
+    end
+  end
+end