useless-doc 0.1.3 → 0.2.0

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

@@ -1,6 +1,12 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
 
+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'
 require 'useless/doc/serialization/dump'
+require 'useless/doc/serialization/load'
 
 describe Useless::Doc::Serialization::Dump do
   describe '.hash_to_json' do
@@ -17,57 +23,51 @@ describe Useless::Doc::Serialization::Dump do
 
   describe '.resource' do
     it 'should convert the specified Doc::Resource instance into JSON' do
-      get_parameter = Useless::Doc::Request::Parameter.new \
-        type:         Useless::Doc::Request::Parameter::Type::PATH,
-        key:          'page',
-        required:     false,
-        default:      1,
-        description:  'The number of the page of twiddles.'
-
-      get_request_header = Useless::Doc::Header.new \
-        key:          'Content',
-        description:  'The type of content.'
-
-      get_request = Useless::Doc::Request.new \
-        parameters: [get_parameter],
-        headers:    [get_request_header],
-        body:       nil
-
-      get_status = Useless::Doc::Response::Status.new \
-        code:         200,
-        description:  'The list was successfully returned.'
-
-      get_response_header = Useless::Doc::Header.new \
+      get_response_header = Useless::Doc::Core::Header.new \
         key:          'Type',
         description:  'The response type.'
 
-      get_response_body_attribute = Useless::Doc::Body::Attribute.new \
+      get_response_body_attribute = Useless::Doc::Core::Body::Attribute.new \
         key:          'name',
         type:         'string',
         required:     true,
         default:      nil,
         description:  'The name of the twiddle.'
 
-      get_response_body = Useless::Doc::Body.new \
+      get_response_body = Useless::Doc::Core::Body.new \
         content_type: 'application/json',
         attributes:   [get_response_body_attribute] 
 
-      get_response = Useless::Doc::Response.new \
-        statuses: [get_status],
-        headers:  [get_response_header],
-        body:     get_response_body
+      get_response = Useless::Doc::Core::Response.new \
+        code:         200,
+        description:  'The list was successfully returned.',
+        headers:      [get_response_header],
+        body:         get_response_body
+
+      get_request_parameter = Useless::Doc::Core::Request::Parameter.new \
+        type:         Useless::Doc::Core::Request::Parameter::Type::PATH,
+        key:          'page',
+        required:     false,
+        default:      1,
+        description:  'The number of the page of twiddles.'
+
+      get_request_header = Useless::Doc::Core::Header.new \
+        key:          'Content',
+        description:  'The type of content.'
 
-      get = Useless::Doc::Action.new \
+      get_request = Useless::Doc::Core::Request.new \
+        method:                   Useless::Doc::Core::Request::Method::GET,
         description:              'See a whole list of twiddles.',
-        method:                   Useless::Doc::Action::Method::GET,
         authentication_required:  false,
-        request:                  get_request,
-        response:                 get_response
+        parameters:               [get_request_parameter],
+        headers:                  [get_request_header],
+        body:                     nil,
+        responses:                [get_response]
 
-      resource = Useless::Doc::Resource.new \
+      resource = Useless::Doc::Core::Resource.new \
         path:         '/twiddles',
         description:  'The full lot of twiddles.',
-        actions:      [get]
+        requests:      [get_request]
 
       json = Useless::Doc::Serialization::Dump.resource(resource)
       hash = Useless::Doc::Serialization::Load.json_to_hash(json)
@@ -75,12 +75,11 @@ describe Useless::Doc::Serialization::Dump do
       hash['path'].should == '/twiddles'
       hash['description'].should == 'The full lot of twiddles.'
 
-      get_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['actions'][0])
-      get_hash['description'].should == 'See a whole list of twiddles.'
-      get_hash['method'].should == 'GET'
-      get_hash['authentication_required'].should be_false
+      get_request_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['requests'][0])
+      get_request_hash['description'].should == 'See a whole list of twiddles.'
+      get_request_hash['method'].should == 'GET'
+      get_request_hash['authentication_required'].should be_false
 
-      get_request_hash = Useless::Doc::Serialization::Load.json_to_hash(get_hash['request'])
       get_request_paramter_hash = Useless::Doc::Serialization::Load.json_to_hash(get_request_hash['parameters'][0])
       get_request_paramter_hash['type'].should == 'path'
       get_request_paramter_hash['key'].should == 'page'
@@ -92,10 +91,9 @@ describe Useless::Doc::Serialization::Dump do
       get_request_header_hash['key'].should == 'Content'
       get_request_header_hash['description'].should == 'The type of content.'
 
-      get_response_hash = Useless::Doc::Serialization::Load.json_to_hash(get_hash['response'])
-      get_response_status_hash = Useless::Doc::Serialization::Load.json_to_hash(get_response_hash['statuses'][0])
-      get_response_status_hash['code'].should == 200
-      get_response_status_hash['description'].should == 'The list was successfully returned.'
+      get_response_hash = Useless::Doc::Serialization::Load.json_to_hash(get_request_hash['responses'][0])
+      get_response_hash['code'].should == 200
+      get_response_hash['description'].should == 'The list was successfully returned.'
 
       get_response_header_hash = Useless::Doc::Serialization::Load.json_to_hash(get_response_hash['headers'][0])
       get_response_header_hash['key'].should == 'Type'

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

@@ -21,79 +21,77 @@ describe Useless::Doc::Serialization::Load do
       document = load_document('twonk.json')
       resource = Useless::Doc::Serialization::Load.resource document.read
 
-      resource.should be_a Useless::Doc::Resource
+      resource.should be_a Useless::Doc::Core::Resource
       resource.path.should == '/twonks/:id'
       resource.description.should == 'The most critical aspect.'
 
-      get = resource.actions.first
-      get.should be_a Useless::Doc::Action
-      get.description.should == 'Retrieve a representation of an individual twonk.'
+      get = resource.requests.first
       get.method.should == 'GET'
+      get.description.should == 'Retrieve a representation of an individual twonk.'
       get.authentication_required.should == false
 
-      get.request.parameters[0].type.should == 'path'
-      get.request.parameters[0].key.should == 'id'
-      get.request.parameters[0].required.should == true
-      get.request.parameters[0].default.should be_nil
-      get.request.parameters[0].description.should == 'The ID of the desired twonk.'
+      get.parameters[0].type.should == 'path'
+      get.parameters[0].key.should == 'id'
+      get.parameters[0].required.should == true
+      get.parameters[0].default.should be_nil
+      get.parameters[0].description.should == 'The ID of the desired twonk.'
 
-      get.request.parameters[1].type.should == 'query'
-      get.request.parameters[1].key.should == 'werp'
-      get.request.parameters[1].required.should == false
-      get.request.parameters[1].default.should == 12
-      get.request.parameters[1].description.should == 'Self-explanatory.'
+      get.parameters[1].type.should == 'query'
+      get.parameters[1].key.should == 'werp'
+      get.parameters[1].required.should == false
+      get.parameters[1].default.should == 12
+      get.parameters[1].description.should == 'Self-explanatory.'
 
-      get.request.headers[0].key.should == 'User-Agent'
-      get.request.headers[0].description.should == 'The thingy you\'re using.'
+      get.headers[0].key.should == 'User-Agent'
+      get.headers[0].description.should == 'The thingy you\'re using.'
 
-      get.response.statuses[0].code.should == 200
-      get.response.statuses[0].description.should == 'The specified twonk was retrieved successfully.'
+      get.responses[0].code.should == 404
+      get.responses[0].description.should == 'A twonk with the specified ID could not be found.'
 
-      get.response.statuses[1].code.should == 404
-      get.response.statuses[1].description.should == 'A twonk with the specified ID could not be found.'
+      get.responses[1].code.should == 200
+      get.responses[1].description.should == 'The specified twonk was retrieved successfully.'
 
-      get.response.body.content_type.should == 'application/json'
+      get.responses[1].body.content_type.should == 'application/json'
 
-      get.response.body.attributes[0].key.should == 'name'
-      get.response.body.attributes[0].type.should == 'string'
-      get.response.body.attributes[0].required.should be_true
-      get.response.body.attributes[0].default.should be_nil
-      get.response.body.attributes[0].description.should == 'The name of the twonk.'
+      get.responses[1].body.attributes[0].key.should == 'name'
+      get.responses[1].body.attributes[0].type.should == 'string'
+      get.responses[1].body.attributes[0].required.should be_true
+      get.responses[1].body.attributes[0].default.should be_nil
+      get.responses[1].body.attributes[0].description.should == 'The name of the twonk.'
 
-      get.response.body.attributes[1].key.should == 'created_by'
-      get.response.body.attributes[1].type.should == 'object'
-      get.response.body.attributes[1].required.should be_true
-      get.response.body.attributes[1].default.should be_nil
-      get.response.body.attributes[1].description.should == 'The short name of the user who created the twonk.'
+      get.responses[1].body.attributes[1].key.should == 'created_by'
+      get.responses[1].body.attributes[1].type.should == 'object'
+      get.responses[1].body.attributes[1].required.should be_true
+      get.responses[1].body.attributes[1].default.should be_nil
+      get.responses[1].body.attributes[1].description.should == 'The short name of the user who created the twonk.'
 
-      put = resource.actions.last
-      put.should be_a Useless::Doc::Action
-      put.description.should =='Update a twonk.'
+      put = resource.requests.last
       put.method.should == 'PUT'
+      put.description.should =='Update a twonk.'
       put.authentication_required.should == true
 
-      put.request.parameters[0].type.should == 'path'
-      put.request.parameters[0].key.should == 'id'
-      put.request.parameters[0].required.should == true
-      put.request.parameters[0].default.should be_nil
-      put.request.parameters[0].description.should == 'The ID of the twonk to be updated.'
+      put.parameters[0].type.should == 'path'
+      put.parameters[0].key.should == 'id'
+      put.parameters[0].required.should == true
+      put.parameters[0].default.should be_nil
+      put.parameters[0].description.should == 'The ID of the twonk to be updated.'
 
-      put.request.body.content_type.should == 'application/x-www-form-urlencoded'
+      put.body.content_type.should == 'application/x-www-form-urlencoded'
 
-      put.request.body.attributes[0].key.should == 'name'
-      put.request.body.attributes[0].type.should == 'string'
-      put.request.body.attributes[0].required.should be_true
-      put.request.body.attributes[0].default.should be_nil
-      put.request.body.attributes[0].description.should == 'The name of the twonk.'
+      put.body.attributes[0].key.should == 'name'
+      put.body.attributes[0].type.should == 'string'
+      put.body.attributes[0].required.should be_true
+      put.body.attributes[0].default.should be_nil
+      put.body.attributes[0].description.should == 'The name of the twonk.'
 
-      put.request.body.attributes[1].key.should == 'hoinked_by'
-      put.request.body.attributes[1].type.should == 'number'
-      put.request.body.attributes[1].required.should be_false
-      put.request.body.attributes[1].default.should == 3
-      put.request.body.attributes[1].description.should == 'The ID of the person who hoinked this twonk.'
+      put.body.attributes[1].key.should == 'hoinked_by'
+      put.body.attributes[1].type.should == 'number'
+      put.body.attributes[1].required.should be_false
+      put.body.attributes[1].default.should == 3
+      put.body.attributes[1].description.should == 'The ID of the person who hoinked this twonk.'
 
-      put.response.statuses[0].code.should == 201
-      put.response.statuses[0].description.should == 'The specified twonk was updated successfully.'
+      put.responses[0].code.should == 201
+      put.responses[0].description.should == 'The specified twonk was updated successfully.'
     end
   end
 end

data/spec/useless/doc/sinatra_spec.rb

@@ -1,7 +1,9 @@
 require File.dirname(__FILE__) + '/../../spec_helper'
 
+require 'rack/test'
 require 'sinatra/base'
 require 'useless/doc/sinatra'
+require 'useless/doc/serialization/load'
 
 describe Useless::Doc::Sinatra do
   class DocApp < Sinatra::Base
@@ -9,11 +11,9 @@ describe Useless::Doc::Sinatra do
 
     doc '/some-resources' do
       get 'Get all of these resources' do
-        request do
-          parameter 'since', 'Only resources after this date.'
-        end
+        parameter 'since', 'Only resources after this date.'
 
-        response do
+        response 200, 'The responses were fetched correctly.' do
           body do
             attribute 'name', 'The name of the resource.'
           end
@@ -21,15 +21,11 @@ describe Useless::Doc::Sinatra do
       end
 
       post 'Make a new resource' do
-        request do
-          body do
-            attribute 'name', 'The name of the resource.'
-          end
+        body do
+          attribute 'name', 'The name of the resource.'
         end
 
-        response do
-          status 201, 'The resource was successfully created.'
-        end
+        response 201, 'The resource was successfully created.'
       end
     end
 
@@ -52,13 +48,13 @@ describe Useless::Doc::Sinatra do
     options 'http://some-api.granmal.com/some-resources'
     resource = Useless::Doc::Serialization::Load.resource(last_response.body)
 
-    get = resource.actions.find { |action| action.method == Useless::Doc::Action::Method::GET }
+    get = resource.requests.find { |request| request.method == Useless::Doc::Core::Request::Method::GET }
     get.description.should == 'Get all of these resources'
-    get.request.parameters.first.key.should == 'since'
+    get.parameters.first.key.should == 'since'
 
-    post = resource.actions.find { |action| action.method == Useless::Doc::Action::Method::POST }
+    post = resource.requests.find { |request| request.method == Useless::Doc::Core::Request::Method::POST }
     post.description.should == 'Make a new resource'
-    post.response.statuses.first.code.should == 201
+    post.responses[0].code.should == 201
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-04 00:00:00.000000000 Z
+date: 2013-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -152,21 +152,18 @@ files:
 - README.md
 - Rakefile
 - lib/useless/doc.rb
-- lib/useless/doc/action.rb
-- lib/useless/doc/body.rb
+- lib/useless/doc/core/body.rb
+- lib/useless/doc/core/header.rb
+- lib/useless/doc/core/request.rb
+- lib/useless/doc/core/resource.rb
+- lib/useless/doc/core/response.rb
 - lib/useless/doc/dsl.rb
-- lib/useless/doc/header.rb
 - lib/useless/doc/rack/application.rb
 - lib/useless/doc/rack/proxy.rb
 - lib/useless/doc/rack/retriever.rb
 - lib/useless/doc/rack/stylesheet.rb
 - lib/useless/doc/rack/transform.rb
 - lib/useless/doc/rack/ui.rb
-- lib/useless/doc/request.rb
-- lib/useless/doc/request/parameter.rb
-- lib/useless/doc/resource.rb
-- lib/useless/doc/response.rb
-- lib/useless/doc/response/status.rb
 - lib/useless/doc/serialization/dump.rb
 - lib/useless/doc/serialization/load.rb
 - lib/useless/doc/sinatra.rb

data/lib/useless/doc/action.rb

@@ -1,50 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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/header.rb

@@ -1,24 +0,0 @@
-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/request/parameter.rb

@@ -1,47 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

data/lib/useless/doc/resource.rb

@@ -1,29 +0,0 @@
-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.rb

@@ -1,29 +0,0 @@
-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