api_canon 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ae973a42fab02db3f846d289447747a5cb35460
-  data.tar.gz: 963a6ebde8bd3d854afbb64ff694e43fd20c4343
+  metadata.gz: 47daa06eee0e9801cdd6d0476a52006585b96e87
+  data.tar.gz: d424093588fe923332278cbd7d8f2515abdcf704
 SHA512:
-  metadata.gz: f2b597c23d3dfaa4daca2351c242123008ac3985488ab97abfd27adda7d9b2a93cce84ba3964613f9f3a0ffcc68022a49ee6a0306bfdfd9804e4e12825d8b846
-  data.tar.gz: f302da8afcc840853dabee58982860f19c9dac85571275f113cb37212435eb76274ce1fefffad43a7ddf0db7fa91aaa34444e0efd10d090ee8c7056b5640940b
+  metadata.gz: 0826027c44ce02123906d4f9c42cf1fade9c6908043ae9fe428bd562eae832202b515932035882fe9017844721d9808bf07036cd03d1dc119d02952a31e64dfd
+  data.tar.gz: 54c41a3748d0443521fea10d78c9b11545fcb9899510c0022b9df100f8062d37971a0f7de4f62a7222bcdfbe4a5ec463c0b646f6c0449c94055999b5f450ddda

data/lib/api_canon.rb

@@ -14,6 +14,7 @@ module ApiCanon
       require 'api_canon/document'
       require 'api_canon/documented_action'
       require 'api_canon/documented_param'
+      require 'api_canon/documented_model'
       require 'api_canon/documentation_store'
       require 'api_canon/swagger/base'
       require 'api_canon/swagger/api_declaration'
@@ -62,10 +63,9 @@ module ApiCanon
     # @param block [&block] Begins the controller documentation DSL
     # @see ApiCanon::Document#describe
     def document_controller(opts={}, &block)
-      document = DocumentationStore.fetch controller_path
-      document ||= Document.new controller_path, controller_name, opts
-      document.instance_eval &block if block_given?
-      DocumentationStore.store document
+      document(opts) do |document|
+        document.instance_eval &block if block_given?
+      end
     end
 
     # document_method is used to describe the actions in your controller (your API actions)
@@ -82,15 +82,41 @@ module ApiCanon
     # @see ApiCanon::DocumentedAction#describe
     # @see ApiCanon::DocumentedAction#param
     # @see ApiCanon::DocumentedAction#response_code
-    def document_method(method_name,&block)
+    def document_method(method_name, &block)
+      document do |document|
+        documented_action = ApiCanon::DocumentedAction.new method_name, controller_name
+        documented_action.instance_eval &block if block_given?
+        document.add_action documented_action
+      end
+    end
+
+    # document_model is used to describe response object models
+    #
+    # Example:
+    #   document_model 'Thing' do
+    #     property :foo, type: 'string', description: 'foo is the type of awesome required', required: true
+    #     property :filter_level, type: 'integer', description: 'filter_level can only be 1, 2, 3 or 4'
+    #   end
+    #
+    # @param model_name [String] The model to be documented
+    # @param block [block] Begins the model documentation DSL
+    # @see ApiCanon::DocumentedModel#property
+    def document_model(id, &block)
+      document do |document|
+        documented_model = ApiCanon::DocumentedModel.new id
+        documented_model.instance_eval &block if block_given?
+        document.add_model documented_model
+      end
+    end
+
+  private
+
+    def document(opts={}, &block)
       document = DocumentationStore.fetch controller_path
-      document ||= Document.new controller_path, controller_name
-      documented_action = ApiCanon::DocumentedAction.new method_name, controller_name
-      documented_action.instance_eval &block if block_given?
-      document.add_action documented_action
+      document ||= Document.new controller_path, controller_name, opts
+      block.call document if block_given?
       DocumentationStore.store document
     end
   end
 
-
 end

data/lib/api_canon/document.rb

@@ -2,12 +2,13 @@ module ApiCanon
   class Document
     include ActiveModel::Serialization
     attr_reader :description, :controller_path, :controller_name, :version, :sidebar_link
-    attr_accessor :documented_actions
+    attr_accessor :documented_actions, :documented_models
     def initialize(controller_path, controller_name, opts={})
       @controller_path = controller_path
       @controller_name = controller_name
       @version = opts[:version]
       self.display_name = opts[:as]
+      @documented_models = {}
       @documented_actions = []
     end
     # The describe method is used as a DSL method in the document_controller block,
@@ -34,5 +35,8 @@ module ApiCanon
     def add_action(documented_action)
       @documented_actions << documented_action unless @documented_actions.map(&:action_name).include?(documented_action.action_name)
     end
+    def add_model(documented_model)
+      @documented_models[documented_model.id] = documented_model
+    end
   end
 end

data/lib/api_canon/documented_action.rb

@@ -1,7 +1,7 @@
 module ApiCanon
   class DocumentedAction
     include ActiveModel::Serialization
-    attr_reader :params, :response_codes, :description, :action_name,
+    attr_reader :params, :response_codes, :response_model_name, :description, :action_name,
       :controller_name, :http_method
     def initialize(action_name, controller_name)
       @action_name = action_name
@@ -20,7 +20,7 @@ module ApiCanon
         else "GET"
       end
 
-      @response_codes={}
+      @response_codes = {}
     end
     # The param method describes and gives examples for the parameters your
     # API action can take.
@@ -50,6 +50,12 @@ module ApiCanon
     def param(param_name, options={})
       @params[param_name] = DocumentedParam.new param_name, self, options
     end
+    # The response_class method allows you to specify name of a model describing the response
+    # @see ApiCanon::ClassMethods#document_model
+    #
+    def response_class(model_name)
+      @response_model_name = model_name
+    end
     # The response_code method will be used as a DSL method in the
     # document_method block to describe what you mean when your action returns
     # the given response code.  It currently does nothing.

data/lib/api_canon/documented_model.rb

@@ -0,0 +1,13 @@
+module ApiCanon
+  class DocumentedModel
+    include ActiveModel::Serialization
+    attr_reader :id, :properties
+    def initialize(id)
+      @id = id
+      @properties = {}
+    end
+    def property(name, opts={})
+      @properties[name] = opts
+    end
+  end
+end

data/lib/api_canon/swagger/api_declaration.rb

@@ -2,10 +2,16 @@ module ApiCanon
   module Swagger
     class ApiDeclaration < ApiCanon::Swagger::Base
 
+      attributes :models
+
       def apis
         object.documented_actions.collect { |action| Api.new(action) }
       end
 
+      def models
+        object.documented_models
+      end
+
       class Api < ActiveModel::Serializer
         self.root = false
         attributes :path
@@ -43,8 +49,8 @@ module ApiCanon
           self.root = false
 
           attributes :http_method => :httpMethod,
-            :error_responses => :errorResponses
-            #:response_class => :responseClass
+            :error_responses => :errorResponses,
+            :response_model_name => :responseClass
           attributes :nickname, :parameters, :summary
 
           def nickname
@@ -66,10 +72,6 @@ module ApiCanon
             end
           end
 
-          # def response_class
-          #   object.controller_name.singularize.titlecase
-          # end
-
           def parameters
             object.params.collect do |name, param|
               # Reject format because its not a real param :)
@@ -106,11 +108,11 @@ module ApiCanon
 
             def allowable_values
               if object.values.class == Range
-                  {
-                    :max => object.values.max,
-                    :min => object.values.min,
-                    :valueType => "RANGE"
-                  }
+                {
+                  :max => object.values.max,
+                  :min => object.values.min,
+                  :valueType => "RANGE"
+                }
               elsif object.values.class == Array
                 {
                   :values => object.values,

data/lib/api_canon/version.rb

@@ -1,3 +1,3 @@
 module ApiCanon
-  VERSION = '0.4.5'
+  VERSION = '0.4.6'
 end

data/spec/lib/api_canon/documented_model_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+describe ApiCanon::DocumentedModel do
+  subject { described_class.new 'Thing' }
+
+  describe '#property' do
+    let(:options) { {:type => :string, :required => true} }
+
+    it 'should add to properties' do
+      subject.property :foo, options
+      subject.properties[:foo].should eql(options)
+    end
+  end
+end

data/spec/lib/api_canon/swagger_spec/api_declaration_spec.rb

@@ -4,12 +4,21 @@ describe ApiCanon::Swagger::ApiDeclaration do
   let(:documented_action) {
     documented_action = ApiCanon::DocumentedAction.new('action_name', 'controller_name')
     documented_action.describe 'description'
+    documented_action.response_class 'Thing'
     documented_action.response_code '404', 'reason'
     documented_action.param 'name', :description => 'description', :type => 'string', :default => 'test', :values => (1..10)
     documented_action
   }
+  let(:documented_model) {
+    documented_model = ApiCanon::DocumentedModel.new('Thing')
+    documented_model.property :foo, :type => :string, :required => true
+    documented_model
+  }
+  let(:documented_models) {
+    { 'Thing' => documented_model }
+  }
   let(:data) {
-    double :documented_actions => [ documented_action ], :version => 'master'
+    double :documented_actions => [ documented_action ], :documented_models => documented_models, :version => 'master'
   }
   subject { described_class.new(data) }
 
@@ -44,11 +53,23 @@ describe ApiCanon::Swagger::ApiDeclaration do
                   "required" => false
                 }
               ],
+              "responseClass" => 'Thing',
               "summary" => 'description'
             }
           ]
         }
-      ]
+      ],
+      "models" => {
+        "Thing" => {
+          "id" => "Thing",
+          "properties" => {
+            "foo" => {
+              "type" => "string",
+              "required" => true
+            }
+          }
+        }
+      }
     }.to_json)
   end
 

data/spec/lib/api_canon_spec.rb

@@ -20,7 +20,7 @@ describe ApiCanon do
     let(:api_document) { double :api_document }
     context "without a current controller doc" do
       it "creates and stores a new ApiCanon::Document and adds the documented action" do
-        ApiCanon::Document.should_receive(:new).with('fake', 'fake').and_return(api_document)
+        ApiCanon::Document.should_receive(:new).with('fake', 'fake', {}).and_return(api_document)
         ApiCanon::DocumentationStore.instance.should_receive(:store).with(api_document)
         api_document.should_receive :add_action
         fake_controller.send(:document_method, :index, &(Proc.new {}))

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: api_canon
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - Cameron Walsh
 - Leon Dewey
+- Ben Tillman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-20 00:00:00.000000000 Z
+date: 2013-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -145,6 +146,7 @@ description: |-
 email:
 - cameron.walsh@gmail.com
 - leon@leondewey.com
+- ben.tillman@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -159,6 +161,7 @@ files:
 - app/controllers/api_canon_controller.rb
 - app/helpers/api_canon/api_canon_view_helper.rb
 - lib/api_canon/documented_param.rb
+- lib/api_canon/documented_model.rb
 - lib/api_canon/version.rb
 - lib/api_canon/documented_action.rb
 - lib/api_canon/documentation_store.rb
@@ -175,6 +178,7 @@ files:
 - README.md
 - spec/spec_helper.rb
 - spec/lib/api_canon/documented_param_spec.rb
+- spec/lib/api_canon/documented_model_spec.rb
 - spec/lib/api_canon/swagger_spec/api_declaration_spec.rb
 - spec/lib/api_canon/swagger_spec/resource_listing_spec.rb
 - spec/lib/api_canon/documented_action_spec.rb
@@ -184,7 +188,7 @@ files:
 - spec/internal/config/database.yml
 - spec/internal/config/routes.rb
 - spec/internal/log/test.log
-homepage: http://github.com/cwalsh/api_canon
+homepage: http://github.com/westfield/api_canon
 licenses:
 - MIT
 metadata: {}
@@ -212,6 +216,7 @@ summary: Declarative documentation generator for APIs.
 test_files:
 - spec/spec_helper.rb
 - spec/lib/api_canon/documented_param_spec.rb
+- spec/lib/api_canon/documented_model_spec.rb
 - spec/lib/api_canon/swagger_spec/api_declaration_spec.rb
 - spec/lib/api_canon/swagger_spec/resource_listing_spec.rb
 - spec/lib/api_canon/documented_action_spec.rb