useless-doc 0.1.0

data/lib/useless/doc/resource.rb

@@ -0,0 +1,29 @@
+module Useless
+  module Doc
+
+    # 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] actions
+    #   @return [Array<Action>] documentation for the available actions for the
+    #     resource.
+    #
+    class Resource
+
+      attr_reader :path, :description, :actions
+
+      # @param [Hash] attrs corresponds to the class's instance attributes.
+      #
+      def initialize(attrs = {})
+        @path         = attrs[:path]
+        @description  = attrs[:description]
+        @actions      = attrs[:actions]
+      end
+    end
+  end
+end

data/lib/useless/doc/response/status.rb

@@ -0,0 +1,27 @@
+module Useless
+  module Doc
+    class Response
+
+      # Documentation for a response status for an API action.
+      #
+      # @!attribute [r] code
+      #   @return [Integer] the HTTP status code of the response.
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the rationale for
+      #     the response.
+      #
+      class Status
+
+        attr_reader :code, :description
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @code         = attrs[:code]
+          @description  = attrs[:description]
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/response.rb

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

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

@@ -0,0 +1,122 @@
+require 'oj'
+
+module Useless
+  module Doc
+    module Serialization
+      module Dump
+
+        # Converts a hash to a JSON representation.
+        #
+        # @param [Hash, String] hash the hash to be converted.
+        #
+        # @raise [ArgumentError] if json is not a Hash, String or IO.
+        #
+        # @return [String] a JSON representation corresponding to the
+        #   specified hash.
+        #
+        def self.hash_to_json(hash)
+          hash.is_a?(String) ? hash : Oj.dump(hash)
+        end
+
+        # Converts +Doc::Resource+ instance to a JSON representation.
+        #
+        # @param [Doc::Resource] resource the resource to be converted to JSON.
+        #
+        # @return [String] a JSON representation of the specified resource.
+        #
+        def self.resource(resource)
+          if resource
+            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)
+          end
+        end
+
+        # @api private
+        def self.request(request)
+          if request
+            hash_to_json \
+              'parameters' => request.parameters.map { |parameter| request_parameter(parameter) },
+              'headers' => request.headers.map { |header| header(header) },
+              'body' => body(request.body)
+          end
+        end
+
+        # @api private
+        def self.response(response)
+          if response
+            hash_to_json \
+              'statuses' => response.statuses.map { |status| response_status(status) },
+              'headers' => response.headers.map { |header| header(header) },
+              'body' => body(response.body)
+          end
+        end
+
+        # @api private
+        def self.request_parameter(parameter)
+          if parameter
+            hash_to_json \
+              'type' => parameter.type,
+              'key' => parameter.key,
+              'required' => parameter.required,
+              'default' => parameter.default,
+              'description' => parameter.description
+          end
+        end
+
+        # @api private
+        def self.header(header)
+          if header
+            hash_to_json \
+              'key' => header.key,
+              'description' => header.description
+          end
+        end
+
+        # @api private
+        def self.response_status(status)
+          if status
+            hash_to_json \
+              'code' => status.code,
+              'description' => status.description
+          end
+        end
+
+        # @api private
+        def self.body(body)
+          if body
+            hash_to_json \
+              'content_type' => body.content_type,
+              'attributes' => body.attributes.map { |attribute| body_attribute(attribute) }
+          end
+        end
+
+        # @api private
+        def self.body_attribute(attribute)
+          if attribute
+            hash_to_json \
+              'key' => attribute.key,
+              'type' => attribute.type,
+              'required' => attribute.required,
+              'default' => attribute.default,
+              'description' => attribute.description
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+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'
+
+module Useless
+  module Doc
+    module Serialization
+      module Load
+
+        # Converts a JSON representation to a hash.
+        #
+        # @param [String, Hash] json the JSON representation to be converted.
+        #
+        # @raise [ArgumentError] if json is not a Hash, String or IO.
+        #
+        # @return [Hash] a hash corresponding to the specified JSON representation.
+        #
+        def self.json_to_hash(json)
+          json.is_a?(Hash) ? json : Oj.load(json)
+        end
+
+        # Converts a JSON represntation to an instance of +Doc::Resource+
+        #
+        # @param [String, Hash] json the JSON representation to be converted to
+        #   a resource.
+        #
+        # @return [Doc::Resource] the resource corresponding to the specified
+        #   JSON.
+        #
+        def self.resource(json)
+          hash = json_to_hash json
+
+          actions = (hash['actions'] || []).map do |json|
+            action(json)
+          end
+
+          Useless::Doc::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
+        end
+
+        # @api private
+        def self.request(json)
+          hash = json_to_hash json
+
+          parameters = (hash['parameters'] || []).map do |json|
+            request_parameter json
+          end
+
+          headers = (hash['headers'] || []).map do |json|
+            header json
+          end
+
+          if hash['body']
+            body = body hash['body']
+          end
+
+          Useless::Doc::Request.new \
+            parameters: parameters,
+            headers:    headers,
+            body:       body
+        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
+
+          if hash['body']
+            body = body hash['body']
+          end
+
+          Useless::Doc::Response.new \
+            statuses: statuses,
+            headers:  headers,
+            body:     body
+        end
+
+        # @api private
+        def self.request_parameter(json)
+          hash = json_to_hash json
+
+          Useless::Doc::Request::Parameter.new \
+            type:         hash['type'],
+            key:          hash['key'],
+            required:     hash['required'],
+            default:      hash['default'],
+            description:  hash['description']
+        end
+
+        # @api private
+        def self.header(json)
+          hash = json_to_hash json
+
+          Useless::Doc::Header.new \
+            key:          hash['key'],
+            description:  hash['description']
+        end
+
+        # @api private
+        def self.body(json)
+          hash = json_to_hash json
+
+          attributes = (hash['attributes'] || []).map do |json|
+            body_attribute json
+          end
+
+          Useless::Doc::Body.new \
+            content_type: hash['content_type'],
+            attributes:   attributes
+        end
+
+        # @api private
+        def self.body_attribute(json)
+          hash = json_to_hash json
+
+          Useless::Doc::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
+end

data/lib/useless/doc/sinatra.rb

@@ -0,0 +1,48 @@
+require 'sinatra'
+
+require 'useless/doc/dsl'
+require 'useless/doc/serialization/dump'
+
+module Useless
+  module Doc
+    module Sinatra
+
+      # 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)
+        end
+      end
+    end
+  end
+end
+
+Sinatra.register Useless::Doc::Sinatra

data/lib/useless/doc/ui/godel/stylesheet.css

@@ -0,0 +1 @@
+body { color: #333; }

data/lib/useless/doc/ui/godel/template.mustache

@@ -0,0 +1,199 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>{{path}} | doc.useless.io</title>
+  <link href="/doc.css" media="screen" rel="stylesheet" type="text/css" />
+</head>
+<body>
+
+  <h1>{{path}}</h1>
+
+  <p>{{description}}</p>
+
+  {{#actions}}
+    <section>
+      <h2>{{method}}</h2>
+
+      <p>{{description}}</p>
+
+      <ul>
+        <li>{{authentication_requirement}}</li>
+      </ul>
+
+      {{#request}}
+        <section>
+          <h3>Request</h3>
+
+          {{#parameters?}}
+            <section>
+              <h4>Parameters</h4>
+              <table>
+                <th>
+                  <tr>
+                    <td>Name</td>
+                    <td>Type</td>
+                    <td>Required</td>
+                    <td>Default</td>
+                    <td>Description</td>
+                  <tr>
+                </th>
+                <tbody>
+                  {{#parameters}}
+                    <tr>
+                      <td>{{key}}</td>
+                      <td>{{type}}</td>
+                      <td>{{required}}</td>
+                      <td>{{default}}</td>
+                      <td>{{description}}</td>
+                    </tr>
+                  {{/parameters}}
+                </tbody>
+              </table>
+            </section>
+          {{/parameters?}}
+
+          {{#headers?}}
+            <section>
+              <h4>Headers</h4>
+              <table>
+                <th>
+                  <tr>
+                    <td>Name</td>
+                    <td>Description</td>
+                  <tr>
+                </th>
+                <tbody>
+                  {{#headers}}
+                    <tr>
+                      <td>{{key}}</td>
+                      <td>{{description}}</td>
+                    </tr>
+                  {{/headers}}
+                </tbody>
+              </table>
+            </section>
+          {{/headers?}}
+
+          {{#body}}
+            <section>
+              <h4>Body</h4>
+
+              <ul>
+                <li>{{content_type}}</li>
+              </ul>
+
+              <table>
+                <th>
+                  <tr>
+                    <td>Name</td>
+                    <td>Type</td>
+                    <td>Required</td>
+                    <td>Default</td>
+                    <td>Description</td>
+                  <tr>
+                </th>
+                <tbody>
+                  {{#attributes}}
+                    <tr>
+                      <td>{{key}}</td>
+                      <td>{{type}}</td>
+                      <td>{{required}}</td>
+                      <td>{{default}}</td>
+                      <td>{{description}}</td>
+                    </tr>
+                  {{/attributes}}
+                </tbody>
+              </table>
+            </section>
+          {{/body}}
+
+        </section>
+      {{/request}}
+
+      {{#response}}
+        <section>
+          <h3>Response</h3>
+
+          {{#statuses?}}
+            <section>
+              <h4>Statuses</h4>
+              <table>
+                <th>
+                  <tr>
+                    <td>Code</td>
+                    <td>Description</td>
+                  <tr>
+                </th>
+                <tbody>
+                  {{#statuses}}
+                    <tr>
+                      <td>{{code}}</td>
+                      <td>{{description}}</td>
+                    </tr>
+                  {{/statuses}}
+                </tbody>
+              </table>
+            </section>
+          {{/statuses?}}
+
+          {{#headers?}}
+            <section>
+              <h4>Headers</h4>
+              <table>
+                <th>
+                  <tr>
+                    <td>Name</td>
+                    <td>Description</td>
+                  <tr>
+                </th>
+                <tbody>
+                  {{#headers}}
+                    <tr>
+                      <td>{{key}}</td>
+                      <td>{{description}}</td>
+                    </tr>
+                  {{/headers}}
+                </tbody>
+              </table>
+            </section>
+          {{/headers?}}
+
+          {{#body}}
+            <section>
+              <h4>Body</h4>
+
+              <ul>
+                <li>{{content_type}}</li>
+              </ul>
+
+              <table>
+                <th>
+                  <tr>
+                    <td>Name</td>
+                    <td>Type</td>
+                    <td>Required</td>
+                    <td>Default</td>
+                    <td>Description</td>
+                  <tr>
+                </th>
+                <tbody>
+                  {{#attributes}}
+                    <tr>
+                      <td>{{key}}</td>
+                      <td>{{type}}</td>
+                      <td>{{required}}</td>
+                      <td>{{default}}</td>
+                      <td>{{description}}</td>
+                    </tr>
+                  {{/attributes}}
+                </tbody>
+              </table>
+            </section>
+          {{/body}}
+
+        </section>
+      {{/response}}
+    </section>
+  {{/actions}}
+
+</body>