useless-doc 0.1.3 → 0.2.0

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

@@ -0,0 +1,60 @@
+module Useless
+  module Doc
+    module Core
+
+      # 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
+end

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

@@ -0,0 +1,26 @@
+module Useless
+  module Doc
+    module Core
+
+      # 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
+end

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

@@ -0,0 +1,106 @@
+module Useless
+  module Doc
+    module Core
+
+      # Documentation for an HTTP request.
+      #
+      # @!attribute [r] method
+      #   @return [String] the request's HTTP method.
+      #   @see Useless::Doc::Core::Request::Method
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the request.
+      #
+      # @!attribute [r] authentication_required
+      #   @return [Boolean] whether or not the user needs to authenticate in
+      #     order to perform this request.
+      #
+      # @!attribute [r] parameters
+      #   @return [Array<Request::Parameter>] possible parameters for the
+      #     request.
+      #   @see Useless::Doc::Core::Request::Parameter
+      #
+      # @!attribute [r] headers
+      #   @return [Array<Header>] possible headers for the request.
+      #   @see Useless::Doc::Core::Heaader
+      #
+      # @!attribute [r] body
+      #   @return [Body] the body of the request.
+      #   @see Useless::Doc::Core::Body
+      #
+      # @!attribute [r] responses
+      #   @return [Array<Response>] possible responses to the request.
+      #   @see Useless::Doc::Core::Response
+      #
+      class Request
+
+        module Method
+          GET     = 'GET'
+          HEAD    = 'HEAD'
+          POST    = 'POST'
+          PUT     = 'PUT'
+          PATCH   = 'PATCH'
+          DELETE  = 'DELETE'
+          TRACE   = 'TRACE'
+          CONNECT = 'CONNECT'
+        end
+
+        attr_accessor :method, :description, :authentication_required,
+          :parameters, :headers, :body, :responses
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @method                   = attrs[:method]
+          @description              = attrs[:description]
+          @authentication_required  = attrs[:authentication_required]
+          @parameters               = attrs[:parameters]
+          @headers                  = attrs[:headers]
+          @body                     = attrs[:body]
+          @responses                = attrs[:responses]
+        end
+
+        # 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
+end

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

@@ -0,0 +1,32 @@
+module Useless
+  module Doc
+    module Core
+
+      # Documentation for an API resource.
+      #
+      # @!attribute [r] path
+      #   @return [String] the path segment of the resource URL.
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the resource.
+      #
+      # @!attribute [r] requests
+      #   @return [Array<Request>] requests that could possibly be made
+      #     against this resource.
+      #   @see Useless::Doc::Core::Request
+      #
+      class Resource
+
+        attr_reader :path, :description, :requests
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @path         = attrs[:path]
+          @description  = attrs[:description]
+          @requests     = attrs[:requests]
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/{response/status.rb → core/response.rb}

@@ -1,8 +1,8 @@
 module Useless
   module Doc
-    class Response
+    module Core
 
-      # Documentation for a response status for an API action.
+      # Documentation for an HTTP response.
       #
       # @!attribute [r] code
       #   @return [Integer] the HTTP status code of the response.
@@ -11,15 +11,23 @@ module Useless
       #   @return [String] a description of the rationale for
       #     the response.
       #
-      class Status
-
-        attr_reader :code, :description
+      # @!attribute [r] headers
+      #   @return [Array<Header>] the significant headers of the response.
+      #   @see Useless::Doc::Core::Header
+      #
+      # @!attribute [r] body
+      #   @return [Body] the body of the response.
+      #
+      class Response
+        attr_accessor :code, :description, :status, :headers, :body
 
         # @param [Hash] attrs corresponds to the class's instance attributes.
         #
         def initialize(attrs = {})
           @code         = attrs[:code]
           @description  = attrs[:description]
+          @headers      = attrs[:headers]
+          @body         = attrs[:body]
         end
       end
     end

data/lib/useless/doc/dsl.rb

@@ -1,11 +1,8 @@
-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'
+require 'useless/doc/core/body'
+require 'useless/doc/core/header'
+require 'useless/doc/core/request'
+require 'useless/doc/core/resource'
+require 'useless/doc/core/response'
 
 module Useless
   module Doc
@@ -19,15 +16,10 @@ module Useless
     #
     #     get 'Returns a full listing of the resources.' do
     #       authentication_required false
+    #       parameter 'page', 'The page of resources to be returned.'
+    #       header 'X-Twiddle', 'The twiddle threshold.'
     #
-    #       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.'
-    #
+    #       response 200, 'The resources were returned successfully.' do
     #         header 'X-Twonk', 'The twonk coefficient.'
     #
     #         body do
@@ -44,7 +36,7 @@ module Useless
         module ClassMethods
           def build(attributes = {}, &block)
             resource = new(attributes)
-            resource.instance_eval(&block)
+            resource.instance_eval(&block) if block_given?
             resource.generate
           end
         end
@@ -59,7 +51,7 @@ module Useless
 
         def generate
           name = self.class.name.split('::').last
-          klass = eval("Doc::#{name}")
+          klass = eval("Doc::Core::#{name}")
           klass.new(@attributes)
         end
 
@@ -72,7 +64,7 @@ module Useless
         include DSL::Member
 
         def default_attributes
-          { actions: [] }
+          { requests: [] }
         end
 
         def path(path)
@@ -84,48 +76,52 @@ module Useless
         end
 
         def get(description = nil, &block)
-          method(Doc::Action::Method::GET, description, &block)
+          method(Doc::Core::Request::Method::GET, description, &block)
         end
 
         def head(description = nil, &block)
-          method(Doc::Action::Method::HEAD, description, &block)
+          method(Doc::Core::Request::Method::HEAD, description, &block)
         end
 
         def post(description = nil, &block)
-          method(Doc::Action::Method::POST, description, &block)
+          method(Doc::Core::Request::Method::POST, description, &block)
         end
 
         def put(description = nil, &block)
-          method(Doc::Action::Method::PUT, description, &block)
+          method(Doc::Core::Request::Method::PUT, description, &block)
         end
 
         def patch(description = nil, &block)
-          method(Doc::Action::Method::PATCH, description, &block)
+          method(Doc::Core::Request::Method::PATCH, description, &block)
         end
 
         def delete(description = nil, &block)
-          method(Doc::Action::Method::DELETE, description, &block)
+          method(Doc::Core::Request::Method::DELETE, description, &block)
         end
 
         def trace(description = nil, &block)
-          method(Doc::Action::Method::TRACE, description, &block)
+          method(Doc::Core::Request::Method::TRACE, description, &block)
         end
 
         def connect(description = nil, &block)
-          method(Doc::Action::Method::CONNECT, description, &block)
+          method(Doc::Core::Request::Method::CONNECT, description, &block)
         end
 
         private
 
         def method(type, description, &block)
           attributes = { method: type, description: description }
-          @attributes[:actions] << Action.build(attributes, &block)
+          @attributes[:requests] << Request.build(attributes, &block)
         end
       end
 
-      class Action
+      class Request
         include DSL::Member
 
+        def default_attributes
+          { parameters: [], headers: [], responses: [] }
+        end
+
         def description(description)
           @attributes[:description] = description
         end
@@ -134,51 +130,43 @@ module Useless
           @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)
+          parameter = Doc::Core::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
+          header = Doc::Core::Header.new key: key, description: description
           @attributes[:headers] << header
         end
 
         def body(&block)
           @attributes[:body] = Body.build({}, &block)
         end
+
+        def response(code, description, &block)
+          response = Response.build({ code: code, description: description }, &block)
+          @attributes[:responses] << response
+        end
       end
 
       class Response
         include DSL::Member
 
         def default_attributes
-          { statuses: [], headers: [] }
+          { headers: [] }
+        end
+
+        def code(code)
+          @attributes[:code] = code
         end
 
-        def status(code, description)
-          status = Doc::Response::Status.new code: code, description: description
-          @attributes[:statuses] << status
+        def description(description)
+          @attributes[:description] = description
         end
 
         def header(key, description)
-          header = Doc::Header.new key: key, description: description
+          header = Doc::Core::Header.new key: key, description: description
           @attributes[:headers] << header
         end
 
@@ -199,7 +187,7 @@ module Useless
         end
 
         def attribute(key, description, attributes = {})
-          attribute = Doc::Body::Attribute.new attributes.merge(key: key, description: description)
+          attribute = Doc::Core::Body::Attribute.new attributes.merge(key: key, description: description)
           @attributes[:attributes] << attribute
         end
       end

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

@@ -1,5 +1,4 @@
 require 'uri'
-require 'typhoeus'
 require 'rack/request'
 
 module Useless
@@ -39,7 +38,7 @@ module Useless
 
           request = ::Rack::Request.new(env)
 
-          if valid_subdomain?(request.url)
+          if true or valid_subdomain?(request.url)
             url = Proxy.transform_url(request.url)
 
             if json = env['useless.doc.retriever'].retrieve(url)

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

@@ -1,3 +1,5 @@
+require 'typhoeus'
+
 module Useless
   module Doc
     module Rack

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

@@ -29,19 +29,7 @@ module Useless
             hash_to_json \
               'path' => resource.path,
               'description' => resource.description,
-              'actions' => resource.actions.map { |action| action(action) }
-          end
-        end
-
-        # @api private
-        def self.action(action)
-          if action
-            hash_to_json \
-              'description' => action.description,
-              'method' => action.method,
-              'authentication_required' => action.authentication_required,
-              'request' => request(action.request),
-              'response' => response(action.response)
+              'requests' => resource.requests.map { |request| request(request) }
           end
         end
 
@@ -49,9 +37,13 @@ module Useless
         def self.request(request)
           if request
             hash_to_json \
+              'method' => request.method,
+              'description' => request.description,
+              'authentication_required' => request.authentication_required,
               'parameters' => request.parameters.map { |parameter| request_parameter(parameter) },
               'headers' => request.headers.map { |header| header(header) },
-              'body' => body(request.body)
+              'body' => body(request.body),
+              'responses' => request.responses.map { |response| response(response) }
           end
         end
 
@@ -59,7 +51,8 @@ module Useless
         def self.response(response)
           if response
             hash_to_json \
-              'statuses' => response.statuses.map { |status| response_status(status) },
+              'code' => response.code,
+              'description' => response.description,
               'headers' => response.headers.map { |header| header(header) },
               'body' => body(response.body)
           end

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

@@ -1,13 +1,10 @@
 require 'oj'
 
-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'
+require 'useless/doc/core/body'
+require 'useless/doc/core/header'
+require 'useless/doc/core/request'
+require 'useless/doc/core/resource'
+require 'useless/doc/core/response'
 
 module Useless
   module Doc
@@ -37,34 +34,14 @@ module Useless
         def self.resource(json)
           hash = json_to_hash json
 
-          actions = (hash['actions'] || []).map do |json|
-            action(json)
+          requests = (hash['requests'] || []).map do |json|
+            request json
           end
 
-          Useless::Doc::Resource.new \
+          Useless::Doc::Core::Resource.new \
             path:         hash['path'],
             description:  hash['description'],
-            actions:      actions
-        end
-
-        # @api private
-        def self.action(json)
-          hash = json_to_hash json
-
-          if hash['request']
-            request = request hash['request']
-          end
-
-          if hash['response']
-            response = response hash['response']
-          end
-
-          Useless::Doc::Action.new \
-            description:              hash['description'],
-            method:                   hash['method'],
-            authentication_required:  hash['authentication_required'],
-            request:                  request,
-            response:                 response
+            requests:     requests
         end
 
         # @api private
@@ -83,20 +60,24 @@ module Useless
             body = body hash['body']
           end
 
-          Useless::Doc::Request.new \
-            parameters: parameters,
-            headers:    headers,
-            body:       body
+          responses = (hash['responses'] || []).map do |json|
+            response json
+          end
+
+          Useless::Doc::Core::Request.new \
+            method:                   hash['method'],
+            description:              hash['description'],
+            authentication_required:  hash['authentication_required'],
+            parameters:               parameters,
+            headers:                  headers,
+            body:                     body,
+            responses:                responses
         end
 
         # @api private
         def self.response(json)
           hash = json_to_hash json
 
-          statuses = (hash['statuses'] || []).map do |json|
-            response_statuses json
-          end
-
           headers = (hash['headers'] || []).map do |json|
             header json
           end
@@ -105,17 +86,18 @@ module Useless
             body = body hash['body']
           end
 
-          Useless::Doc::Response.new \
-            statuses: statuses,
-            headers:  headers,
-            body:     body
+          Useless::Doc::Core::Response.new \
+            code:         hash['code'],
+            description:  hash['description'], 
+            headers:      headers,
+            body:         body
         end
 
         # @api private
         def self.request_parameter(json)
           hash = json_to_hash json
 
-          Useless::Doc::Request::Parameter.new \
+          Useless::Doc::Core::Request::Parameter.new \
             type:         hash['type'],
             key:          hash['key'],
             required:     hash['required'],
@@ -127,7 +109,7 @@ module Useless
         def self.header(json)
           hash = json_to_hash json
 
-          Useless::Doc::Header.new \
+          Useless::Doc::Core::Header.new \
             key:          hash['key'],
             description:  hash['description']
         end
@@ -140,7 +122,7 @@ module Useless
             body_attribute json
           end
 
-          Useless::Doc::Body.new \
+          Useless::Doc::Core::Body.new \
             content_type: hash['content_type'],
             attributes:   attributes
         end
@@ -149,22 +131,13 @@ module Useless
         def self.body_attribute(json)
           hash = json_to_hash json
 
-          Useless::Doc::Body::Attribute.new \
+          Useless::Doc::Core::Body::Attribute.new \
             key:          hash['key'],
             type:         hash['type'],
             required:     hash['required'],
             default:      hash['default'],
             description:  hash['description']
         end
-
-        # @api private
-        def self.response_statuses(json)
-          hash = json_to_hash json
-
-          Useless::Doc::Response::Status.new \
-            code:         hash['code'],
-            description:  hash['description']
-        end
       end
     end
   end