api_canon 0.4.5 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 5ae973a42fab02db3f846d289447747a5cb35460
4
- data.tar.gz: 963a6ebde8bd3d854afbb64ff694e43fd20c4343
3
+ metadata.gz: 47daa06eee0e9801cdd6d0476a52006585b96e87
4
+ data.tar.gz: d424093588fe923332278cbd7d8f2515abdcf704
5
5
  SHA512:
6
- metadata.gz: f2b597c23d3dfaa4daca2351c242123008ac3985488ab97abfd27adda7d9b2a93cce84ba3964613f9f3a0ffcc68022a49ee6a0306bfdfd9804e4e12825d8b846
7
- data.tar.gz: f302da8afcc840853dabee58982860f19c9dac85571275f113cb37212435eb76274ce1fefffad43a7ddf0db7fa91aaa34444e0efd10d090ee8c7056b5640940b
6
+ metadata.gz: 0826027c44ce02123906d4f9c42cf1fade9c6908043ae9fe428bd562eae832202b515932035882fe9017844721d9808bf07036cd03d1dc119d02952a31e64dfd
7
+ data.tar.gz: 54c41a3748d0443521fea10d78c9b11545fcb9899510c0022b9df100f8062d37971a0f7de4f62a7222bcdfbe4a5ec463c0b646f6c0449c94055999b5f450ddda
data/lib/api_canon.rb CHANGED
@@ -14,6 +14,7 @@ module ApiCanon
14
14
  require 'api_canon/document'
15
15
  require 'api_canon/documented_action'
16
16
  require 'api_canon/documented_param'
17
+ require 'api_canon/documented_model'
17
18
  require 'api_canon/documentation_store'
18
19
  require 'api_canon/swagger/base'
19
20
  require 'api_canon/swagger/api_declaration'
@@ -62,10 +63,9 @@ module ApiCanon
62
63
  # @param block [&block] Begins the controller documentation DSL
63
64
  # @see ApiCanon::Document#describe
64
65
  def document_controller(opts={}, &block)
65
- document = DocumentationStore.fetch controller_path
66
- document ||= Document.new controller_path, controller_name, opts
67
- document.instance_eval &block if block_given?
68
- DocumentationStore.store document
66
+ document(opts) do |document|
67
+ document.instance_eval &block if block_given?
68
+ end
69
69
  end
70
70
 
71
71
  # document_method is used to describe the actions in your controller (your API actions)
@@ -82,15 +82,41 @@ module ApiCanon
82
82
  # @see ApiCanon::DocumentedAction#describe
83
83
  # @see ApiCanon::DocumentedAction#param
84
84
  # @see ApiCanon::DocumentedAction#response_code
85
- def document_method(method_name,&block)
85
+ def document_method(method_name, &block)
86
+ document do |document|
87
+ documented_action = ApiCanon::DocumentedAction.new method_name, controller_name
88
+ documented_action.instance_eval &block if block_given?
89
+ document.add_action documented_action
90
+ end
91
+ end
92
+
93
+ # document_model is used to describe response object models
94
+ #
95
+ # Example:
96
+ # document_model 'Thing' do
97
+ # property :foo, type: 'string', description: 'foo is the type of awesome required', required: true
98
+ # property :filter_level, type: 'integer', description: 'filter_level can only be 1, 2, 3 or 4'
99
+ # end
100
+ #
101
+ # @param model_name [String] The model to be documented
102
+ # @param block [block] Begins the model documentation DSL
103
+ # @see ApiCanon::DocumentedModel#property
104
+ def document_model(id, &block)
105
+ document do |document|
106
+ documented_model = ApiCanon::DocumentedModel.new id
107
+ documented_model.instance_eval &block if block_given?
108
+ document.add_model documented_model
109
+ end
110
+ end
111
+
112
+ private
113
+
114
+ def document(opts={}, &block)
86
115
  document = DocumentationStore.fetch controller_path
87
- document ||= Document.new controller_path, controller_name
88
- documented_action = ApiCanon::DocumentedAction.new method_name, controller_name
89
- documented_action.instance_eval &block if block_given?
90
- document.add_action documented_action
116
+ document ||= Document.new controller_path, controller_name, opts
117
+ block.call document if block_given?
91
118
  DocumentationStore.store document
92
119
  end
93
120
  end
94
121
 
95
-
96
122
  end
@@ -2,12 +2,13 @@ module ApiCanon
2
2
  class Document
3
3
  include ActiveModel::Serialization
4
4
  attr_reader :description, :controller_path, :controller_name, :version, :sidebar_link
5
- attr_accessor :documented_actions
5
+ attr_accessor :documented_actions, :documented_models
6
6
  def initialize(controller_path, controller_name, opts={})
7
7
  @controller_path = controller_path
8
8
  @controller_name = controller_name
9
9
  @version = opts[:version]
10
10
  self.display_name = opts[:as]
11
+ @documented_models = {}
11
12
  @documented_actions = []
12
13
  end
13
14
  # The describe method is used as a DSL method in the document_controller block,
@@ -34,5 +35,8 @@ module ApiCanon
34
35
  def add_action(documented_action)
35
36
  @documented_actions << documented_action unless @documented_actions.map(&:action_name).include?(documented_action.action_name)
36
37
  end
38
+ def add_model(documented_model)
39
+ @documented_models[documented_model.id] = documented_model
40
+ end
37
41
  end
38
42
  end
@@ -1,7 +1,7 @@
1
1
  module ApiCanon
2
2
  class DocumentedAction
3
3
  include ActiveModel::Serialization
4
- attr_reader :params, :response_codes, :description, :action_name,
4
+ attr_reader :params, :response_codes, :response_model_name, :description, :action_name,
5
5
  :controller_name, :http_method
6
6
  def initialize(action_name, controller_name)
7
7
  @action_name = action_name
@@ -20,7 +20,7 @@ module ApiCanon
20
20
  else "GET"
21
21
  end
22
22
 
23
- @response_codes={}
23
+ @response_codes = {}
24
24
  end
25
25
  # The param method describes and gives examples for the parameters your
26
26
  # API action can take.
@@ -50,6 +50,12 @@ module ApiCanon
50
50
  def param(param_name, options={})
51
51
  @params[param_name] = DocumentedParam.new param_name, self, options
52
52
  end
53
+ # The response_class method allows you to specify name of a model describing the response
54
+ # @see ApiCanon::ClassMethods#document_model
55
+ #
56
+ def response_class(model_name)
57
+ @response_model_name = model_name
58
+ end
53
59
  # The response_code method will be used as a DSL method in the
54
60
  # document_method block to describe what you mean when your action returns
55
61
  # the given response code. It currently does nothing.
@@ -0,0 +1,13 @@
1
+ module ApiCanon
2
+ class DocumentedModel
3
+ include ActiveModel::Serialization
4
+ attr_reader :id, :properties
5
+ def initialize(id)
6
+ @id = id
7
+ @properties = {}
8
+ end
9
+ def property(name, opts={})
10
+ @properties[name] = opts
11
+ end
12
+ end
13
+ end
@@ -2,10 +2,16 @@ module ApiCanon
2
2
  module Swagger
3
3
  class ApiDeclaration < ApiCanon::Swagger::Base
4
4
 
5
+ attributes :models
6
+
5
7
  def apis
6
8
  object.documented_actions.collect { |action| Api.new(action) }
7
9
  end
8
10
 
11
+ def models
12
+ object.documented_models
13
+ end
14
+
9
15
  class Api < ActiveModel::Serializer
10
16
  self.root = false
11
17
  attributes :path
@@ -43,8 +49,8 @@ module ApiCanon
43
49
  self.root = false
44
50
 
45
51
  attributes :http_method => :httpMethod,
46
- :error_responses => :errorResponses
47
- #:response_class => :responseClass
52
+ :error_responses => :errorResponses,
53
+ :response_model_name => :responseClass
48
54
  attributes :nickname, :parameters, :summary
49
55
 
50
56
  def nickname
@@ -66,10 +72,6 @@ module ApiCanon
66
72
  end
67
73
  end
68
74
 
69
- # def response_class
70
- # object.controller_name.singularize.titlecase
71
- # end
72
-
73
75
  def parameters
74
76
  object.params.collect do |name, param|
75
77
  # Reject format because its not a real param :)
@@ -106,11 +108,11 @@ module ApiCanon
106
108
 
107
109
  def allowable_values
108
110
  if object.values.class == Range
109
- {
110
- :max => object.values.max,
111
- :min => object.values.min,
112
- :valueType => "RANGE"
113
- }
111
+ {
112
+ :max => object.values.max,
113
+ :min => object.values.min,
114
+ :valueType => "RANGE"
115
+ }
114
116
  elsif object.values.class == Array
115
117
  {
116
118
  :values => object.values,
@@ -1,3 +1,3 @@
1
1
  module ApiCanon
2
- VERSION = '0.4.5'
2
+ VERSION = '0.4.6'
3
3
  end
@@ -0,0 +1,13 @@
1
+ require 'spec_helper'
2
+ describe ApiCanon::DocumentedModel do
3
+ subject { described_class.new 'Thing' }
4
+
5
+ describe '#property' do
6
+ let(:options) { {:type => :string, :required => true} }
7
+
8
+ it 'should add to properties' do
9
+ subject.property :foo, options
10
+ subject.properties[:foo].should eql(options)
11
+ end
12
+ end
13
+ end
@@ -4,12 +4,21 @@ describe ApiCanon::Swagger::ApiDeclaration do
4
4
  let(:documented_action) {
5
5
  documented_action = ApiCanon::DocumentedAction.new('action_name', 'controller_name')
6
6
  documented_action.describe 'description'
7
+ documented_action.response_class 'Thing'
7
8
  documented_action.response_code '404', 'reason'
8
9
  documented_action.param 'name', :description => 'description', :type => 'string', :default => 'test', :values => (1..10)
9
10
  documented_action
10
11
  }
12
+ let(:documented_model) {
13
+ documented_model = ApiCanon::DocumentedModel.new('Thing')
14
+ documented_model.property :foo, :type => :string, :required => true
15
+ documented_model
16
+ }
17
+ let(:documented_models) {
18
+ { 'Thing' => documented_model }
19
+ }
11
20
  let(:data) {
12
- double :documented_actions => [ documented_action ], :version => 'master'
21
+ double :documented_actions => [ documented_action ], :documented_models => documented_models, :version => 'master'
13
22
  }
14
23
  subject { described_class.new(data) }
15
24
 
@@ -44,11 +53,23 @@ describe ApiCanon::Swagger::ApiDeclaration do
44
53
  "required" => false
45
54
  }
46
55
  ],
56
+ "responseClass" => 'Thing',
47
57
  "summary" => 'description'
48
58
  }
49
59
  ]
50
60
  }
51
- ]
61
+ ],
62
+ "models" => {
63
+ "Thing" => {
64
+ "id" => "Thing",
65
+ "properties" => {
66
+ "foo" => {
67
+ "type" => "string",
68
+ "required" => true
69
+ }
70
+ }
71
+ }
72
+ }
52
73
  }.to_json)
53
74
  end
54
75
 
@@ -20,7 +20,7 @@ describe ApiCanon do
20
20
  let(:api_document) { double :api_document }
21
21
  context "without a current controller doc" do
22
22
  it "creates and stores a new ApiCanon::Document and adds the documented action" do
23
- ApiCanon::Document.should_receive(:new).with('fake', 'fake').and_return(api_document)
23
+ ApiCanon::Document.should_receive(:new).with('fake', 'fake', {}).and_return(api_document)
24
24
  ApiCanon::DocumentationStore.instance.should_receive(:store).with(api_document)
25
25
  api_document.should_receive :add_action
26
26
  fake_controller.send(:document_method, :index, &(Proc.new {}))
metadata CHANGED
@@ -1,15 +1,16 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: api_canon
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.5
4
+ version: 0.4.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - Cameron Walsh
8
8
  - Leon Dewey
9
+ - Ben Tillman
9
10
  autorequire:
10
11
  bindir: bin
11
12
  cert_chain: []
12
- date: 2013-08-20 00:00:00.000000000 Z
13
+ date: 2013-08-21 00:00:00.000000000 Z
13
14
  dependencies:
14
15
  - !ruby/object:Gem::Dependency
15
16
  name: rails
@@ -145,6 +146,7 @@ description: |-
145
146
  email:
146
147
  - cameron.walsh@gmail.com
147
148
  - leon@leondewey.com
149
+ - ben.tillman@gmail.com
148
150
  executables: []
149
151
  extensions: []
150
152
  extra_rdoc_files: []
@@ -159,6 +161,7 @@ files:
159
161
  - app/controllers/api_canon_controller.rb
160
162
  - app/helpers/api_canon/api_canon_view_helper.rb
161
163
  - lib/api_canon/documented_param.rb
164
+ - lib/api_canon/documented_model.rb
162
165
  - lib/api_canon/version.rb
163
166
  - lib/api_canon/documented_action.rb
164
167
  - lib/api_canon/documentation_store.rb
@@ -175,6 +178,7 @@ files:
175
178
  - README.md
176
179
  - spec/spec_helper.rb
177
180
  - spec/lib/api_canon/documented_param_spec.rb
181
+ - spec/lib/api_canon/documented_model_spec.rb
178
182
  - spec/lib/api_canon/swagger_spec/api_declaration_spec.rb
179
183
  - spec/lib/api_canon/swagger_spec/resource_listing_spec.rb
180
184
  - spec/lib/api_canon/documented_action_spec.rb
@@ -184,7 +188,7 @@ files:
184
188
  - spec/internal/config/database.yml
185
189
  - spec/internal/config/routes.rb
186
190
  - spec/internal/log/test.log
187
- homepage: http://github.com/cwalsh/api_canon
191
+ homepage: http://github.com/westfield/api_canon
188
192
  licenses:
189
193
  - MIT
190
194
  metadata: {}
@@ -212,6 +216,7 @@ summary: Declarative documentation generator for APIs.
212
216
  test_files:
213
217
  - spec/spec_helper.rb
214
218
  - spec/lib/api_canon/documented_param_spec.rb
219
+ - spec/lib/api_canon/documented_model_spec.rb
215
220
  - spec/lib/api_canon/swagger_spec/api_declaration_spec.rb
216
221
  - spec/lib/api_canon/swagger_spec/resource_listing_spec.rb
217
222
  - spec/lib/api_canon/documented_action_spec.rb