Proposal: Implementable Documentation

lib/grape.rb

@@ -94,6 +94,11 @@ module Versioner
   module Util
     autoload :HashStack,         'grape/util/hash_stack'
   end
+
+  module Meta
+    autoload :Description, 'grape/meta/description'
+    autoload :Response,    'grape/meta/response'
+  end
 end
 
 require 'grape/version'

lib/grape/meta/description.rb

@@ -0,0 +1,43 @@
+module Grape
+  module Meta
+    # An object containing descriptive metadata for an
+    # endpoint.
+    class Description
+      def initialize(summary = nil, data = {})
+        @summary = summary
+        @data = data
+        @responses = []
+        @success_response = nil
+        @failure_response = {}
+      end
+
+      def detail(detail = false)
+        @detail = detail if detail
+        @detail = nil if detail.nil?
+        @detail
+      end
+
+      def summary(summary = false)
+        @summary = summary if summary
+        @summary = nil if summary.nil?
+        @summary
+      end
+
+      def response(entity, status, description)
+        response = Response.new(entity, status, description)
+        @responses << response
+        response
+      end
+
+      def success(entity, status, description)
+        @success_response = response(entity, status, description)
+      end
+
+      def failure(name, status, description)
+        failure_response = Response.new(Grape::ErrorEntity.new(name, status, description), status, description)
+        response failure_response
+        @failure_responses[name.to_sym] = failure_response
+      end
+    end
+  end
+end

lib/grape/meta/response.rb

@@ -0,0 +1,11 @@
+module Grape
+  module Meta
+    class Response
+      def initialize(entity_class, status = 200, description = nil)
+        @entity_class = entity
+        @status = status
+        @description = description
+      end
+    end
+  end
+end

spec/grape/meta/description_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe Grape::Meta::Description do
+  subject { Grape::Meta::Description.new }
+
+  describe '#detail' do
+    it 'should set when a value is provided' do
+      subject.detail 'this is detail'
+      expect(subject.detail).to eq('this is detail')
+    end
+
+    it 'should blank when nil is provided' do
+      subject.detail 'foo'
+      subject.detail nil
+      expect(subject.detail).to eq(nil)
+    end
+  end
+
+  describe '#summary' do
+    it 'should be settable in the constructor' do
+      expect(Grape::Meta::Description.new('foo').summary).to eq('foo')
+    end
+  end
+end