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 +4 -4
- data/lib/api_canon.rb +36 -10
- data/lib/api_canon/document.rb +5 -1
- data/lib/api_canon/documented_action.rb +8 -2
- data/lib/api_canon/documented_model.rb +13 -0
- data/lib/api_canon/swagger/api_declaration.rb +13 -11
- data/lib/api_canon/version.rb +1 -1
- data/spec/lib/api_canon/documented_model_spec.rb +13 -0
- data/spec/lib/api_canon/swagger_spec/api_declaration_spec.rb +23 -2
- data/spec/lib/api_canon_spec.rb +1 -1
- metadata +8 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 47daa06eee0e9801cdd6d0476a52006585b96e87
|
4
|
+
data.tar.gz: d424093588fe923332278cbd7d8f2515abdcf704
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
66
|
-
|
67
|
-
|
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
|
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
|
-
|
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
|
data/lib/api_canon/document.rb
CHANGED
@@ -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.
|
@@ -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
|
-
|
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
|
-
|
111
|
-
|
112
|
-
|
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,
|
data/lib/api_canon/version.rb
CHANGED
@@ -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
|
|
data/spec/lib/api_canon_spec.rb
CHANGED
@@ -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.
|
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-
|
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/
|
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
|